Git_Workflow

Git Workflow

This is meant as a quick little guide to formatting patches to send to the mailing list, emailing them out, and applying others’ patches.

For easier setup, you can use these tools to check out repositories automatically and set up the appropriate hooks.

Setup

If you intend to push code to the repos on GitHub, be sure to clone the “SSH” URL, which begins git@github.com:. If you've already cloned the repo, you can edit .git/config in the base of the checkout to reference the SSH-based URL. Otherwise you will be unable to push.

Before composing patches, you should make sure that your .git/config in the base of the checkout includes a section like the following:

subjectprefix = PATCH conductor

This will change the default subject prefix of generated patches to include the project name. This helps make it clear to reviewers what project your patch refers to.

Git Hooks

A number of us make use of git hooks, which can be found in /.git/hooks such as:

• applypatch-msg.sample
• post-receive.sample
• pre-commit
• update
• commit-msg
• post-update.sample
• prepare-commit-msg.sample
• post-commit.sample
• pre-applypatch
• pre-rebase

Conductor config example

You may want to tuck something like the following at the end of /.git/config:

subjectprefix = PATCH conductor
to = mailto:aeolus-devel@lists.fedorahosted.org
denybadwhitespace = true

General Git config tips

You may find some of these handy in your ~/.gitconfig file

email = <you>`gmail.com
name = <Your Name>
[sendemail]
  smtpserver = smtp.gmail.com
  chainreplyto = no
  smtpuser = <you>`gmail.com
  smtpserverport = 587
  smtpencryption = tls
  smtppass = <somepass>
  suppress-cc = all

  st = status
  co = checkout
  ci = commit
  br = branch

  diff = auto
  status = auto
  branch = auto

Patch Standards

• Do include a short summary in your patch as a description, followed by all information that would be useful to a reviewer and/or someone looking back at git history to see what you did. The first line should be one short line, followed by a more detailed explanation. For example:

Fix adding account to pool functionality

We had an issue with blah where we were checking foo instead of bar, this resulted in xyz, and required that we abc to get it correct again.

• Don’t put all that above info in the first line of your patch, it makes it unreadable.
• Do use --compose flag to add a summary explaining your patchset, if you think it will be unclear to a reviewer why this is a set vs a single patch, and any over-arching details that may be missed by reading just the individual commit messages.

Formatting a patch to email

This presupposes that you have some recent commits you wish to send to the list. We use the git format-patch command for this. The command expects a range of commits format. In this example, after commiting a patch named “Don’t set :body in attrs,” I run the following command:

$ git format-patch HEAD^..HEAD 0001-Don-t-set-body-in-attrs.patch

As the terse output indicates, one file was created: 0001-Don-t-set-body-in-attrs.patch. If you view the file in your favorite text editor, you’ll see that it’s essentially an email saved as a text file. The first line of the commit message forms your subject, and subsequent lines are the body. The rest of the email consists of the patch.

Sending an email

After formatting a patch , you probably want to email them. For this, we use the git send-email command, which send each patch as a separate email in a thread.

You’ll probably want to edit your~/.gitconfig to add this section, obviously replacing the example with your actual SMTP server:

smtpserver = smtp.example.com
chainreplyto = no
suppresscc = self

Typically, you would run something like this to send the email:

$ git send-email 0001-Don-t-set-body-in-attrs.patch --compose 0001-Don-t-set-body-in-attrs.patch Who should the emails be sent to? aeolus-devel@lists.fedorahosted.org

The “send-email” command to git requires that the git-email package is installed.

The --compose option is important, as it allows you to write a cover message. This will be sent first, and all the patches are sent as a reply to that post. This keeps emails nicely threaded on the list and allows you to provide some context. Note that the --compose@ will just pull up a fairly blank email in your default text editor; you should make sure things such as the To:, From:, and Subject: lines are correct.

On the aeolus-devel list, it is customary to begin the subject line with something like “[PATCH conductor 0/1]” to indicate that you are sending a patch , it is for conductor , and you are sending one patch.

Applying a patch

Now that you’ve sent your patch, say you want to apply someone else’s patch.

You basically want to save the message in your mail client somehow, and then use git apply to apply the patch. This will apply the patch locally. To save yourself many headaches, you probably want to make sure you’re on the appropriate branch before running this.

The usage would be something like: Save the message in your mail client as ~/patch.txt , and then:

 $ git apply ~/patch.txt

The output will be “Applying: (name of patch)”. If you run git log, you should then see the commit applied.

There is also git am which operates on a mailbox file instead of a patch file.

See Also

• http://aeolusproject.org/patches.html
• Git Workflow Presentation
• help.github.com A wealth of information helpful to first-time git users