diff options
Diffstat (limited to 'doc/git-email.texi')
| -rw-r--r-- | doc/git-email.texi | 359 |
1 files changed, 359 insertions, 0 deletions
diff --git a/doc/git-email.texi b/doc/git-email.texi new file mode 100644 index 0000000..72c4592 --- /dev/null +++ b/doc/git-email.texi @@ -0,0 +1,359 @@ +\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 +@samp{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 +@samp{git format-patch} to generate the patches. + +@item +@samp{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 @samp{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 + +You can install it by cloning this repo and adding @samp{git-email} to +your @samp{load-path}. + +@menu +* Nix:: +@end menu + +@node Nix +@section Nix + +If you are using @uref{https://nixos.wiki/wiki/Flakes, nix flakes}, +three versions of the package are available: + +@itemize +@item +@samp{git-email-full-git} -- This includes all the optional libraries as +is built from the latest master branch. + +@item +@samp{git-email-git} -- This only contains the core `git-email.el` +library and is built from the latest master branch. + +@item +@samp{git-email} -- This is the package from the latest release. +@end itemize + +You can install the package with + +@example +nix profile install "git+https://git.sr.ht/~yoctocell/git-email#git-email@{-full-git,-git@}" +@end example + +@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 @samp{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 @samp{message-mail} function will be used for +composing the message. You can change this to something else by +customizing the @samp{git-email-compose-email-function}. + +@node git-email-format-patch +@subsection git-email-format-patch +@findex git-email-format-patch + +When you invoke @samp{git-email-format-patch}, you will prompted in the +minibuffer for extra arguments to give @samp{git format-patch}. Some common +arguments will be displayed in your completion framework. If you want +to select multiple options, separate them with @samp{,} or whatever the value +of @samp{crm-separator} is. You can add options to the list of candidates by +customizing @samp{git-email-format-patch-extra-args}. +@samp{git-email-format-patch-default-args} contains arguments automatically +passed to @samp{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 @samp{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 @samp{git-email-send-email}. By default, the generated patches will be +deleted, if you don not like this behaviour, call +@samp{git-email-format-patch} with a prefix argument (C-u). + +You can see all the customizable variables running @samp{M-x customize-group} +@samp{<RET> =git-email <RET>}. + +@node Customization options +@chapter Customization options + +@node Sending email +@section Sending email + +@itemize +@vindex git-email-compose-email-function +@item +@samp{git-email-compose-email-function} is the function used to compose an +email, defaults to @samp{mesage-mail}. + +@vindex git-email-send-email-function +@item +@samp{git-email-send-email-function} is the function used to send the +email, defaults to @samp{message-send-and-exit}. + +@vindex git-email-pre-compose-email-hook +@item +@samp{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 +@samp{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 +@samp{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 +@samp{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 +@samp{git-email-get-to-address-function} is a function that returns the +“to” address for a message. The default function runs @samp{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 +@samp{git-email-format-patch-default-args} is a string of arguments to give +@samp{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 +@samp{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 +@samp{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 +@samp{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 @samp{git-email-revision-parser} variable + +@vindex git-email-get-revision-functions +@item +@samp{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 +@samp{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{/}. +@end itemize + +@node Integration with other packages +@chapter Integration with other packages + +@samp{git-email} offers minor modes for Gnus 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 @samp{git-email-magit.el} +library. This will faciliate the transient library, you can send a +patch from the magit status buffer by pressing @samp{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. + +@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 |