Managing a Patch Series with git-series or StGit

Patch Submission Reference covers the plain git format-patch workflow, which is all most contributors need. Some prefer a tool that tracks a series across revisions more directly. This page is a quick reference for the two most common ones — not a replacement for their own documentation, which you should still skim before relying on either.

git-series

git-series tracks a patch series, including its cover letter, as a first-class object — no manual branch bookkeeping, and old versions of the series stay reachable.

git series start my-feature
git series cover                 # write the cover letter; first line is the email subject
git checkout master               # base the series on this branch
git series base HEAD
# ... make commits as usual ...
git series commit -a -m "Version 1"
git series format                 # equivalent of git format-patch; always threaded

Useful commands: git series log (series history), git series status, git series checkout (switch between series, stashing uncommitted work), git series rebase.

For a revision, make further commits, update the cover letter, and reformat:

git series cover
git series commit -a -m "Version 2"
git series format --reroll-count=2

git series format always stores patches in the repository root (no -o option), and always threads the series. Follow the rest of the Patch Submission Reference workflow (add_maintainers.pl, git send-email) unchanged.

StGit

StGit manages your patches as a stack on top of a git branch — closer to Mercurial’s patch queues than to plain git. It’s particularly convenient for jumping between patches in a series during review.

git clone https://xenbits.xen.org/git-http/xen.git
cd xen
stg init
stg branch -c my-feature          # one branch per series

Add a patch, develop, and commit it:

stg new first-patch
# write the commit message when prompted, or leave blank and fill in later
# ... edit files ...
stg refresh                       # records changes into the current patch
stg refresh -e                    # also edit the commit message

stg series lists the stack: applied patches are marked +, unapplied -, and the current patch >. Move between patches with stg pop, stg push, or jump directly with stg goto <patch-name>.

Before sending, make sure the last patch in the series is the current one (stg goto <last-patch>), then follow the normal Patch Submission Reference sending steps. To address review comments on a specific patch:

stg goto <patch-name>
# ... make changes ...
stg refresh -e                    # update the patch and its commit message/changelog

To rebase a series onto a new baseline:

stg branch master
git pull
stg branch my-feature
stg rebase <commit-id>

If patches don’t apply cleanly, StGit stops and reports the conflict — resolve it, then git add the file and run stg refresh followed by stg push to continue.