~yoctocell/git-email

ref: d03cda5836e5408d902422664ea23edd5dd7505d git-email/doc/git-email.texi -rw-r--r-- 11.6 KiB
d03cda58Xinglu Chen git-email: Generate unique buffer names. 4 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
\input texinfo    @c -*- texinfo -*-

@set VERSION 0.2.0

@setfilename git-email.info
@settitle Format and send patches in Emacs
@documentencoding UTF-8
@documentlanguage en

@copying
This manual is for git-email 0.2.0.

Copyright @copyright{} 2021 all contributors
<~yoctocell/git-email-devel@@lists.sr.ht>

@quotation
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, with no Front-Cover Texts,
and with no Back-Cover Texts.  A copy of the license is included in
the section entitled "GNU Free Documentation License".
@end quotation
@end copying

@dircategory Emacs
@direntry
* git-email: (git-email). Format and send patches in Emacs
@end direntry

@finalout
@titlepage
@title git-email reference manual
@subtitle for version @value{VERSION}
@author Xinglu Chen
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top git-email

This manual is for git-email version @value{VERSION}
@end ifnottex


@menu
* Introduction::
* Installation::
* Usage::
* Customization options::
* Integration with other packages::
* Acknowledgements::
* Contributing::

Appendices
* GNU Free Documentation License::

Indices
* Variable Index::
* Lisp Function Index::
* Concept Index::
@end menu

@c @detailmenu
@c --- The Detailed Node Listing ---
@c 
@c Usage
@c 
@c * Send patches::
@c 
@c Send patches
@c 
@c * git-email-send-email::
@c * git-email-format-patch::
@c 
@c Customization options
@c 
@c * Sending email::
@c * Format patches::
@c * Miscellaneous::
@c 
@c Installation
@c 
@c * Nix::
@c 
@c @end detailmenu
@c @end menu

@node Introduction
@chapter Introduction

@samp{git-email} makes it easy to format and send patches via email in
Emacs, it offers two main functions for sending email with Git.

@itemize
@item
@code{git-email-send-email} will send the marked files as patches using your
mail client of choice.  This means that you have to first run
@code{git format-patch} to generate the patches.

@item
@code{git-email-format-patch} will ask you for a base revision and generate
patches for all the changes that occured between the revision and
the current HEAD@.  It will then prepare the patches as email
messages in the same way as @code{git-email-send-email}.
@end itemize

If you want to easily apply patches you have recieved via email, you
should checkout @uref{https://git.kyleam.com/piem, piem}.

@node Installation
@chapter Installation

@samp{git-email} is not yet available in any package repositories, so
you have to install it manually by cloning the Git repo and adding @samp{git-email} to
your @code{load-path}.  Or, you can install it using one of the options
listed below.

@node Guix
@section Guix

You can install git-email with guix by running @command{guix install
--install-from-file=guix.scm}.

@node Usage
@chapter Usage

@node Send patches
@section Send patches

@node git-email-send-email
@subsection git-email-send-email
@findex git-email-send-email

When you are in a dired, vc-dir, or ibuffer buffer, you can mark patch
files and run @code{git-email-send-email} to send the patches.  If you arent
in one of those bufffers, you will be prompted to enter a file path in
the minibuffer.

Once a message has been created, your cursor will automatically be
placed in the appropriate location.  This means that if the subject or
"to" address is empty, the cursor will automatically be there already.

By default, the built-in @code{message-mail} function will be used for
composing the message.  You can change this to something else by
customizing the @code{git-email-compose-email-function}.

@node git-email-format-patch
@subsection git-email-format-patch
@findex git-email-format-patch

When you invoke @code{git-email-format-patch}, you will prompted in the
minibuffer for extra arguments to give @code{git format-patch}.  Some common
arguments will be displayed in your completion framework. If you want
to select multiple options, separate them with @code{,} or whatever the value
of @code{crm-separator} is.  You can add options to the list of candidates by
customizing @code{git-email-format-patch-extra-args}.
@code{git-email-format-patch-default-args} contains arguments automatically
passed to @code{git format-patch} if no extra arguments are given.

After you have entered extra arguments, the minibuffer will prompt you
to select the @emph{base} commit for your patches.  That is, a patch will be
generated for the changes between the @emph{base} commit and the current
HEAD@.  Selecting the second candidate in the list is equivalent to
typing @code{HEAD^1} in the shell.  If you are already in a VC log buffer,
the revision under point will be used automatically.

When the revision has been selected, patches will be generated and you
will be greeted with a message buffer containing a patch, just like
with @code{git-email-send-email}.  By default, the generated patches will be
deleted, if you don not like this behaviour, call
@code{git-email-format-patch} with a prefix argument (C-u).

@findex git-email-rewrite-header
In case you forgot to Cc someone while writing the command line options
for @command{git format-patch}, you can use
@code{git-email-rewrite-header} to add an Email address to Cc to all the
messages.  If you have already put an address in the ``Cc'' field, and
you still want to keep that address, you can invoke
@code{git-email-rewrite-header} with a prefix argument, then the address
to specified will be appended to the ``Cc'' field, rather than
overwriting the old address.

Another use of @code{git-email-rewrite-header} is when you are sending a
multi-patchset series to a mailing list managed by Debbugs.  You first
have to send a message to the mailing list address, then you have to
wait for an ``acknowledgement'' message from Debbugs that tells you the
bug number for the messages.  Once you know the bug number you can send
followup messages to @email{@var{NNN}@@debbugs.gnu.org}, where @var{NNN}
is the bug number.  See @uref{https://debbugs.gnu.org/Advanced.html, the
Debbugs documentation} for more information.  Instead of having to
manually switch to every buffer and add the ``To'' address, you can
simply call @code{git-email-rewrite-header}, specify the ``To'' header,
and then the appropriate Debbugs address.

You can see all the customizable variables running @kbd{M-x
customize-group @key{RET} git-email @key{RET}}.

@node Customization options
@chapter Customization options

@node Sending email
@section Sending email

@itemize
@vindex git-email-compose-email-function
@item
@code{git-email-compose-email-function} is the function used to compose an
email, defaults to @code{mesage-mail}.

@vindex git-email-send-email-function
@item
@code{git-email-send-email-function} is the function used to send the
email, defaults to @code{message-send-and-exit}.

@vindex git-email-pre-compose-email-hook
@item
@code{git-email-pre-compose-email-hook} is a list of functions to be
executed before composing messages.  This useful if you want to do
extra formatting of the message.

@vindex git-email-post-compose-email-hook
@item
@code{git-email-post-compose-email-hook} is a list of functions to be
executed after sending the messages.  You could for example run
‘notmuch new’ to index your messages.

@vindex git-email-headers
@item
@code{git-email-headers} is a list of headers to include in the message,
you probably should not touch this unless you really know what you
are doing.

@vindex git-email-get-files-functions
@item
@code{git-email-get-files-functions} is a list of functions to run to get
a list of patches to send.  The default, there is already support
for dired, ibuffer and vc-dir.

@vindex git-email-get-to-address-function
@item
@code{git-email-get-to-address-function} is a function that returns the
``to'' address for a message.  The default function runs @command{git
config --list} to get the address, this will not work unless you are in
a git repository.
@end itemize

@node Format patches
@section Format patches

@itemize
@vindex git-email-format-patch-default-args
@item
@code{git-email-format-patch-default-args} is a string of arguments to give
@code{git format-patch} by default.  If you choose to give extra arguments,
the default arguments will not be used.

@vindex git-email-format-patch-extra-args
@item
@code{git-email-format-patch-extra-args} is a list of arguments presented
in your completion framework when entering extra arguments to give
to ‘git format-patch’.  These arguments are just there for the sake
of convience, you are not restricted to just the arguments in this
list.

@vindex git-email-revision-limit
@item
@code{git-email-revision-limit} controls the number of revisions to show in
the minibuffer when choosing a base revision.

@vindex git-email-revision-command
@item
@code{git-email-revision-command} is the command to run to get a list of
revisions.  If you change this, you will most likely also have to
change @code{git-email-revision-parser} variable

@vindex git-email-get-revision-functions
@item
@code{git-email-get-revision-functions} is a list of functions to run to
try to get the base revision for the patches.  If all of the
functions return nil, it fallsback to
‘git-email--minibuffer-get-revision’.  By default, it will get the
revision of under point if you are in a VC log buffer.
@end itemize

@node Miscellaneous
@section Miscellaneous

@itemize
@vindex git-email-get-current-project-functions
@item
@code{git-email-get-current-project-functions} is a hook that is executed
to get the path of the current project.  The path must include a
trailing @samp{/}.

@vindex git-email-generate-message-buffer
@item
@code{git-email-generate-message-buffer} controls how message buffer
names are generated.  See the documentation for
@code{message-generate-new-buffers} for more information.

By default the name will have the following format @samp{git-email
unsent patch to *** TO ADDRESS HERE *** *}.
@end itemize

@node Integration with other packages
@chapter Integration with other packages

@samp{git-email} offers minor modes for Gnus, Mu4e, and Notmuch, these
minor modes will just configure some variables for you and provide any
extra functionality as of right now.

There is also integration with magit in the @file{git-email-magit.el}
library.  This will faciliate the transient library, you can send a
patch from the magit status buffer by pressing @kbd{W c s}.

@node Acknowledgements
@chapter Acknowledgements

Thank you Protesilaos Stavrou for your extensive testing and feedback!

Other packages and tools of interest:

@itemize
@cindex public-inbox
@item
@uref{https://git.kyleam.com/piem/, piem} --- gluing together
public-inbox archives and Git.
@end itemize

@itemize
@item
@uref{https://git-send-email.io/, git-send-email.io} --- tutorial for
configuring and using @code{git send-email}.
@end itemize

@node Contributing
@chapter Contributing

You are welcome to send patches and bug reports to the
@uref{https://lists.sr.ht/~yoctocell/git-email-devel, git-email-devel}
mailing list.

Please format commit messages in the ChangeLog format (@pxref{Change
Logs,,, standards, GNU Coding Standards}); you can check the commit log
for examples.

If you are using @uref{https://guix.gnu.org/, GNU Guix}, you can create
a development environment by running @command{guix environment
--load=guix.scm} (see the @file{guix.scm} file for more details).

@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl-1.3.texi

@node Variable Index
@unnumbered Variable Index

@printindex vr

@node Lisp Function Index
@unnumbered Function Index

@printindex fn

@node Concept Index
@unnumbered Concept Index

@printindex cp


@bye