StGIT

From HalyardWiki

If you're working on a large new feature, you may want to send it as a series of patches. Ideally:

1. Each patch should do one thing. (Don't mix totally different changes in the same patch.)
2. After applying each patch, all test cases and Halyard features should still work.
3. When your code is reviewed, you should go back and "refresh" any individual patches that need changes, and then resend the updated patches.

If you want to work in this fashion, then you probably want to check out Stacked GIT. Begin by reading the excellent StGIT tutorial.

Before installing or using StGIT, you should follow the instructions for installing and setting up your Git repository, including setting up your name and email address appropriately.

Contents 1 Installation 2 Basics 3 Send an StGIT patch series to a mailing list 3.1 Alternate setup 4 Rebase an StGIT branch 5 Merge an StGIT branch and commit it with git-svn 6 Applying patches using stg import

[edit] Installation

You can install StGIT 0.13 via Cygwin, or you can install StGIT 0.14.2 from the distribution on the website. StGIT 0.14.2 is highly recommended. To install from the distribution on the website, dowload it, untar it, cd to the directory, run python setup.py install --prefix=/usr/local, and make sure /usr/local/bin is present in your PATH.

If you have problems with StGIT, you may want to read Cygwin on Vista.

[edit] Basics

To create a new StGIT branch:

stg branch -c my-new-feature
stg new groundwork-for-new-feature
# Edit.
stg refresh
# Edit some more.
stg add groundwork.c
stg refresh

The stg refresh command updates the current patch. It's sort of like a commit. Now let's a add a new patch to our series:

stg new new-feature-implementation
# Edit.
stg refresh

Let's take a look at what's going on.

stg status # Like git or svn status
stg series # Show all patches in this series
stg show   # Display diff for current patch

Oops. We forgot to add a file to the groundwork-for-new-feature patch. Let's pop our stack, fix it, and push again.

stg pop
stg add groundwork.h
stg refresh
stg push

[edit] Send an StGIT patch series to a mailing list

OK, we're ready to have this patch reviewed. If we're running StGIT 0.13.x, we first need make sure we have a local SMTP server. We can do this using SSH port fowarding:

ssh -L 25:unixbox:25 unixbox

Now we need to send the actual patch series:

stg mail -a --to='halyard-dev@iml.dartmouth.edu'

When updating and resending a patch, it's polite to include a little log at the bottom of the commit message:

Add support for My New Feature

My new feature is very shiny, and it speeds up I/O
performance by 50%.

v3:
  Fixed bug handling empty list
v2:
  Unit tests now work

You can edit your log message using (in StGIT 0.13):

stg refresh -e

Or (in StGIT 0.14 or later):

stg edit

[edit] Alternate setup

You can set up StGIT to make it easier to send patches, without having to specify the list address every time or set up SSH tunnels. To avoid having to set up the tunnel, add the following to your ~/.gitconfig. Note that you should only do this if you're comfortable with your smtp password being in plain text on your computer.

[stgit]
	smtpserver = <your smtp server> # mailhub.dartmouth.edu, if you're at Dartmouth
        smtpuser = <your username>
        smtppassword = <your password>
        smtptls = [yes|no]              # yes if you're using mailhub

To automatically send patches to the Halyard mailing list, create the file halyard/.git/patchmail.tmpl with the following contents:

To: halyard-dev@iml.dartmouth.edu
From: %(sender)s
Subject: [%(prefix)sPATCH%(version)s%(number)s] %(shortdescr)s

%(fromauth)s%(longdescr)s
---

%(diffstat)s

%(diff)s

Now, you should be able to send the current patch series using the following, without having to set up a tunnel first:

stg mail -a

[edit] Rebase an StGIT branch

If you want to rebase your patch series against the latest master branch, you can run the following commands:

git checkout master
git pull
stg branch my-new-feature
stg rebase master

[edit] Merge an StGIT branch and commit it with git-svn

You can safely ignore this if you don't have commit privileges on the master Subversion server.

First, rebase the StGIT branch against the latest trunk:

git checkout master
git svn rebase
stg branch my-new-feature
stg rebase master

Next, turn the StGIT patches into regular commits:

stg commit

Now, merge the branch and dcommit it:

git checkout master
git merge --ff my-new-feature
git branch -d my-new-feature
git svn dcommit

[edit] Applying patches using stg import

In stg, the easiest way to apply a patch from a file is to run

stg import <patchfile>