This page walks you through an example of using StGit along side of Git to manipulate a series of patches.

Prerequisite Software

The tools outlined in this document can be installed to an Ubuntu system by running the command:

$ sudo apt-get install git gitk stgit

Getting Started With a Local Branch

Start off with the linux kernel for a standard example:

$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git

You'll now need to create a local branch you can work from. You can find the latest stable kernel release with something like (this filters out release candidates which you might want in some cases):

$ git tag | grep -v "rc" | sort | tail -n1
v2.6.37

$ git branch mywork v2.6.37
$ git checkout mywork

You can also run gitk to see that your branch is on 2.6.37:

gitk view of 2.6.37 tag

Also the “git-show-branch” can verify this:

$ git show-branch mywork 

[mywork] Linux 2.6.37

Let StGit Help

$ stg init
#Create a patch named “fix1”
$ stg new -m "fix1 subject"$'\n'$'\n'"message body" fix1

#validate its in your patch series:
$ stg series
> fix1

#git log will also show the fix (your commit id and message may differ)
$ git log --oneline -1
a7b8e2e fix1 subject

#we'll pretend to change the spelling of “color” in a file:
$ sed -i -e 's/color/colour/g' Documentation/fb/framebuffer.txt 

#git status will show its been updated:
$ git status
# On branch mywork
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#       modified:   Documentation/fb/framebuffer.txt
#
no changes added to commit (use "git add" and/or "git commit -a")

You can view the diff two ways:

$ git diff
diff --git a/Documentation/fb/framebuffer.txt b/Documentation/fb/framebuffer.txt
index 58c5ae2..8cc2843 100644
--- a/Documentation/fb/framebuffer.txt
+++ b/Documentation/fb/framebuffer.txt
@@ -75,7 +75,7 @@ appears in the special file is not the whole memory, but the f
 some video hardware.

 /dev/fb* also allows several ioctls on it, by which lots of information about
-the hardware can be queried and set. The color map handling works via ioctls,
+the hardware can be queried and set. The colour map handling works via ioctls,
...

Gitk will also show this:

gitk view of uncomitted changes

As you can see from gitk this change is not yet a part of the StGit patch we defined. You can “commit” this change with:

$ stg status
M Documentation/fb/framebuffer.txt
$ stg refresh 
Now at patch "fix1"
$ stg status
$ git status
# On branch mywork
nothing to commit (working directory clean)

Now you need to create another related fix.

$ stg new -m "fix2 subject"$'\n'$'\n'"message body" fix2
Invoking the editor: "vi .stgit-new.txt" ... done
Now at patch "fix2"
$ stg series 
+ fix1
> fix2
# Note the “>” show's what patch is active so if you want to make a change back on fix1 you can:

$ stg pop
Popped fix2
Now at patch "fix1"

$ stg series 
> fix1
- fix2
$stg push #get's us back to fix2

Now we'll do another “related” fix:

$ sed -i -e 's/flavor/flavour/g' Documentation/RCU/lockdep.txt 
$ stg status
M Documentation/RCU/lockdep.txt
$ stg diff 
diff --git a/Documentation/RCU/lockdep.txt b/Documentation/RCU/lockdep.txt
index d7a49b2..620e936 100644
--- a/Documentation/RCU/lockdep.txt
+++ b/Documentation/RCU/lockdep.txt
@@ -1,8 +1,8 @@
 RCU and lockdep checking

-All flavors of RCU have lockdep checking available, so that lockdep is
-aware of when each task enters and leaves any flavor of RCU read-side
-critical section.  Each flavor of RCU is tracked separately (but note
+All flavours of RCU have lockdep checking available, so that lockdep is
+aware of when each task enters and leaves any flavour of RCU read-side
+critical section.  Each flavour of RCU is tracked separately (but note
...

#to commit these changes to fix2:
$ stg refresh Documentation/RCU/lockdep.txt

Correcting Mistakes

At this point you realize your commit messages are not accurate. This can be fixed with:

#NOTE: the stg edit command will launch you into $EDITOR to make the change
$ stg edit fix1
Invoking the editor: "vi .stgit-edit.txt" ... done
Popped fix2
Pushing patch "fix2" ... done

$ stg edit fix2
Invoking the editor: "vi .stgit-edit.txt" ... done
$ git log --oneline -2
3007e62 change spelling of flavor
616814d change spelling of color

You also now realize there's one more “color” correction to make in patch1:

$ stg pop
Popped fix2
Now at patch "fix1"

$ sed -i -e 's/color/colour/g' Documentation/fb/sh7760fb.txt 
$ stg refresh 
Now at patch "fix1"

$ stg series 
> fix1
- fix2
$ git log --oneline -1
bc9cb62 change spelling of color
$ stg push
Pushing patch "fix2" ... done
Now at patch "fix2"

Since fix1 and fix2 are bad labels to work with we can also rename those now:

$ stg rename fix1 colour-patch
Renaming patch "fix1" to "colour-patch" ... done
$ stg rename fix2 flavour-patch
Renaming patch "fix2" to "flavour-patch" ... done
$ stg series 
+ colour-patch
> flavour-patch

You also realized your patches need to be re-orderd. You can “sink” the flavour-patch with:

$ stg sink -t colour-patch flavour-patch 
Popped flavour-patch -- colour-patch
Pushing patch "flavour-patch" ... done
Pushing patch "colour-patch" ... done
Now at patch "colour-patch"
$ stg series 
+ flavour-patch
> colour-patch

Gitk will show:

gitk view of patch re-order

Rebasing/Preparing for Submission

At this point your changes are stable and ready to be shared. However, time has gone by and your branch is out of date. You've discovered you need your changes based on the v2.6.38-rc1 level of code. You can “rebase” your changes to that with:

$ git checkout master
$ git pull #incase you don't have v2.6.38-rc1 in your repo yet
$ git checkout mywork
$ stg rebase v2.6.38-rc1 
Checking for changes in the working directory ... done
Popping all applied patches ... done
Rebasing to "v2.6.38-rc1" ... done
Pushing patch "flavour-patch" ... done
Pushing patch "colour-patch" ... done
Now at patch "colour-patch"

$ git log --oneline -n3
1c7f8fd change spelling of color
b82b443 change spelling of flavor
c56eb8f Linux 2.6.38-rc1


CategoryHowTo

Resources/HowTo/Git/StGitDemo (last modified 2013-11-29 11:49:04)