-
Notifications
You must be signed in to change notification settings - Fork 0
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.
If you intend to push code to the repos on GitHub, be sure to clone the
“SSH” URL, which begins
gitgithub.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:
[format]
subjectprefix = PATCH conductor
(Substitute the appropriate project name for “conductor” on other projects — e.g., aeolus-website, configure, etc.)
This will change the default [PATCH] subject prefix of generated patches to include the project name. This helps make it clear to reviewers what project your patch refers to.
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
You may want to tuck something like the following at the end of /.git/config:
[format]
subjectprefix = PATCH conductor
[sendemail]
to =
[email protected]
[hooks]
denybadwhitespace = true
You may find some of these handy in your ~/.gitconfig file (Gmail is just for example)
[user]
email = gmail.com name = <Your Name> [sendemail] smtpserver = smtp.gmail.com chainreplyto = no smtpuser = <you>gmail.com
smtpserverport = 587
smtpencryption = tls
smtppass =
suppress-cc = all
[alias]
st = status
co = checkout
ci = commit
br = branch
[color]
diff = auto
status = auto
branch = auto
- 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
--composeflag 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.
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
(HEAD^ refers to one commit back, so HEAD^..HEAD means “from one
commit ago to the previous commit”. For multiple commits, rather than
HEAD^^^, you could do HEAD~3. (Where the “3” is the number of carets
you would have used.). 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.
After formatting a patch (or series of patches), 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:
[sendemail]
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?
[email protected]
The “send-email” command to git requires that the git-email package is
installed. (yum install git-email will do the trick.)
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 (1) you are sending a patch (to help people with mail filters), (2) it is for conductor (or whatever other component you use), and (3) you are sending one patch. (The cover letter is the 0th.)
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 (basically, commit) 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 ~/patch1.txt (or whatever), and then:
$ git apply ~/patch1.txt
The (terse) 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. (This is handy in mutt which allows you to pipe an entire message to a command, skipping the step of having to save it.)
- http://aeolusproject.org/patches.html
- Git Workflow Presentation [ODP]
- help.github.com - A wealth of information helpful to first-time git users