====== Git ======

Git version control quick reference.

===== git send-email =====

Setup email server:
<code>
[sendemail]
	smtpserver = mail.example.org
	smtpuser = you@example.org
	smtpencryption = ssl
	smtpserverport = 465
</code><code>
git config --global user.email "you@example.org"
git config --global user.name "Your Name"
</code>

Make some changes, then commit
<code>
echo 'hi' > stuff.txt
git add stuff.txt
git commit -m "my cool commit"
</code>

Send the Patch:
<code>
git send-email --to="dev@example.org" HEAD^
</code>

On getting feedback, amend commit, then send (''%%--annotate%%'' edits the email before sending):
<code>
git commit -a --amend
git send-email --to"dev@example.org" --annotate -v2 HEAD^
</code>

When annotating an email, add prose under the ''%%---%%'' for details that //should not// be included in the git log.

<code>
Subject: [PATCH v2] erm what the σ + jω

---
oh my god its 's'!!!

your-name | 1 +
1 file changed, 1 insertion(+)
</code>

==== Patches with Cover Letter ====

Not all changes are straightforward and self-contained. When a change requires several commits, a cover letter can be added as the starting point of the email thread. 

<code>git send-email --cover-letter origin/master</code>

This will generate an extra email template with placeholders for the subject and main body: 

<code>
Subject: [PATCH 0/3] *** SUBJECT HERE ***

*** BLURB HERE ***

your-name (3):
  core: Move reusable foo logic to a new function
  core: Add new flag to the aforementioned foo()
  cmd: New foo subcommand similar to bar

 core.c  |  38 ++++++++------
 cmd.c   |  13 ++++
 2 files changed, 34 insertions(+), 17 deletions(-)

--
</code>

In the example above, the subject could become:
<code>Subject: [PATCH 0/3] Derive a foo subcommand from bar</code>

The cover letter could then explain why a new subcommand is needed, and why it cannot or should not be implemented as an option to the existing subcommand that shares some aspects. A cover letter offers a convenient place to provide the rationale behind a change.

Since the default template includes a short log, it can also be useful to add a summary of the structure of a patch series. It could for example start with refactoring commits to prepare the actual change, and that change could also span multiple commits. A complicated change is likely easier to implement and review when decomposed into smaller logical chunks with a clear progression.

Other relevant information that does not necessarily belong in a commit log can be added to a cover letter, such as benchmark results, links to discussions on other forums or literature on the topic. As such, even a single patch submission may benefit from a cover letter.

==== Settings of interest ====

<code>
git config format.subjectPrefix "PATCH foobar"
git config --global sendemail.annotate yes
git config format.signOff yes
git config sendemail.to "dev@example.org"
</code>

===== Push local branch to named remote branch =====
Pass in ''-u'' to set the origin default.
<code>
git push <remote> <local branch>:<remote branch>
</code>