StGit Crash Course

This tutorial should get you started with the StGit tool, which is intended for conveniently maintaining a patch series on top of a Git repository. You can reorder, push and pop patches, merge them together and mail them out individually or as a patch series.

It is assumed that you know basics of Git at this point, but you can actually get around by just knowing how to clone the repository and add/remove files from the working copy:

  git clone url
  git add file
  git rm file

Before running any command the first time, it's recommended that you at least quickly skim through its manual page. Many of the commands have very useful and interesting features (that we won't list here) and sometimes there are some extra notes you might want to know. There's a quick usage help available for the StGit command using stg help command.

To initialize StGit on the current branch of your (probably freshly cloned) repository, stg init.

To add a new patch to your patch stack, do:

stg new invent-some-patch-id
...edit patch description...
...hack hack hack in the tree...
stg refresh
...possibly hack some more...
stg refresh

There you go. You can add several patches this way, then use stg series to list them - the patches with minus sign are not applied, the patches with plus sign are applied. You can pop the latest applied patch using stg pop and apply any of the yet unapplied patches using stg push. At any point you can edit the current tree to update your top currently updated patch - use the refresh command to record your changes (use -e to update the patch description as well). stg show will show the current (or any) patch.

If you want to update your patches to be against the latest version of a remote branch, use the stg pull command. It will essentially merely pop all the patches, then update your current branch (which probably has no local changes by then) to the upstream revision using git pull, then push your patches back on top of the new base. Conflicts may occur - then you need to resolve them and tell StGit using the stg resolved command (you may find the -a flag useful) and then update the patch using stg refresh and resume the patches pushing by doing stg push -a.

To submit your patches using email, use the stg mail command. It is very powerful and can submit individual patches, arbitrary patch series or your whole stack, send covermails and make your patches followups of other mails. You will probably want to create simple email templates for your patch. You can find all the details in the stg help mail output.

If you have any question or problem which is not obvious from the documentation, please contact us at the Git mailing list at git@vger.kernel.org. We hope you enjoy using Git!