#+TITLE: git-email
#+AUTHOR: Xinglu Chen
#+EMAIL: public@yoctocell.xyz

* Introduction
=git-email= integrates git and email with Emacs, it offers two main
functions for sending email with git.

- =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
  =git format-patch= to generate the patches.
  
- =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 =git-email-send-email=.

If you want to easily apply patches you have recieved via email, you
should checkout [[https://git.kyleam.com/piem][piem]].

* Demo
[[file:demo.gif]]

* Features
** Send patches
When you are in a dired, vc-dir, or ibuffer buffer, you can mark patch
files and run =git-email-send-email= to send the patches.  If you aren't
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 =message-mail= function will be used for
composing the message.  You can change this to something else by
customizing the =git-email-compose-email-function=.

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

After you have entered extra arguments, the minibuffer will prompt you
to select the /base/ commit for your patches.  That is, a patch will be
generated for the changes between the /base/ commit and the current
HEAD.  Selecting the second candidate in the list is equivalent to
typing =HEAD^1= in the shell.

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 =git-email-send-email=.  By default, the generated patches will be
deleted, if you don not like this behaviour, call
=git-email-format-patch= with a prefix argument (C-u).

You can see all the customizable variables running =M-x =customize-group=
=<RET> =git-email <RET>=.

** Integration with other packages
=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 =git-email-magit.el=
library.  This will faciliate the transient library, you can send a
patch from the magit status buffer by pressing =W c s=.

* Installation
You can install it by cloning this repo and adding =git-email.el= to your =load-path=.

* Related packages
- [[https://git.kyleam.com/piem/][piem]] - gluing together public-inbox archives and git

* Contributing
You can send patches and bug reports to the [[https://lists.sr.ht/~yoctocell/git-email-devel][git-email-devel]] mailing list.

*Note:* The README.md is generated from README.org