##############
StGit is a command-line application that provides functionality
-similar to htmllink:http://savannah.nongnu.org/projects/quilt/[Quilt]
+similar to link:http://savannah.nongnu.org/projects/quilt/[Quilt]
(i.e. pushing/popping patches to/from a stack), but using Git instead
of +diff+ and +patch+. StGit stores its patches in a Git repository as
normal Git commits, and provides a number of commands to manipulate
This tutorial assumes you are already familiar with the basics of Git
(for example, branches, commits, and conflicts). For more information
-on Git, see manlink:git[1] or htmllink:http://git.or.cz/[the Git home
+on Git, see linkman:git[1] or link:http://git.or.cz/[the Git home
page].
$ man stg-<cmd>
-(The documentation is also available in htmllink:stg.html[HTML
+(The documentation is also available in link:stg.html[HTML
format].)
that you have already created, using +git init+ or +git clone+. So get
one of those; if you don't have one at hand, try for example
- $ git clone http://homepage.ntlworld.com/cmarinas/stgit.git
+ $ git clone git://repo.or.cz/stgit.git
$ cd stgit
-Before you can create StGit patches, you have to run stglink:init[]:
+Before you can create StGit patches, you have to run linkstg:init[]:
$ stg init
want to have StGit patches in another branch too, you need to run +stg
init+ again in that branch.)
-NOTE: As a shortcut, stglink:clone[] will run +git clone+ followed by
+NOTE: As a shortcut, linkstg:clone[] will run +git clone+ followed by
+stg init+ for you.
This will create a patch called +my-first-patch+, and open an editor
to let you edit the patch's commit message. (If you don't give a name
on the command line, StGit will make one up based on the first line of
-the commit message.) This patch is empty, as stglink:show[] will tell
+the commit message.) This patch is empty, as linkstg:show[] will tell
you:
$ stg show
$ stg status
M stgit/main.py
-Then stgsublink:refresh[] the patch:
+Then linkstgsub:refresh[] the patch:
$ stg refresh
finally:
(I'm assuming you're already familiar with
-htmllink:http://en.wikipedia.org/wiki/Diff#Unified_format[unified
+link:http://en.wikipedia.org/wiki/Diff#Unified_format[unified
diff] patches like this from Git, but it's really quite simple; in
this example, I've added the +$$print 'My first patch!'$$+ line to the
file +stgit/main.py+, at around line 171.)
Since the patch is also a regular Git commit, you can also look at it
-with regular Git tools such as manlink:gitk[].
+with regular Git tools such as linkman:gitk[].
Creating another patch
----------------------
$ stg refresh
Note that we can give the commit message on the command line, and that
-it doesn't matter whether we run stglink:new[] before or after we edit
+it doesn't matter whether we run linkstg:new[] before or after we edit
the files.
So now we have two patches:
+ my-first-patch # This is my first patch
> credit # Give me some credit
-stglink:series[] lists the patches from bottom to top; +$$+$$+ means
+linkstg:series[] lists the patches from bottom to top; +$$+$$+ means
that a patch is 'applied', and +>+ that it is the 'current', or
topmost, patch.
If we want to make further changes to the topmost patch, we just edit
the files and run +stg refresh+. But what if we wanted to change
-+my-first-patch+? The simplest way is to stgsublink:pop[] the +credit+
++my-first-patch+? The simplest way is to linkstgsub:pop[] the +credit+
patch, so that +my-first-patch+ becomes topmost again:
$ stg pop credit
> my-first-patch # This is my first patch
- credit # Give me some credit
-stglink:series[] now shows that +my-first-patch+ is topmost again,
-which means that stglink:refresh[] will update it with any changes we
+linkstg:series[] now shows that +my-first-patch+ is topmost again,
+which means that linkstg:refresh[] will update it with any changes we
make.
The minus sign says that +credit+ is 'unapplied' -- this means that
it's been temporarily put aside. If you look at the +AUTHORS+ file,
you'll see that our change to it is gone; and tools such as
-manlink:gitk[] will not show it, because it's been edited out of the
-Git history. But it's just one stglink:push[] command away from being
+linkman:gitk[] will not show it, because it's been edited out of the
+Git history. But it's just one linkstg:push[] command away from being
restored:
$ stg push credit
Fast-forwarded patch "credit"
Now at patch "credit"
-NOTE: You can omit the patch name argument to stglink:push[] and
-stglink:pop[]. If you do, you will push the next unapplied patch, and
+NOTE: You can omit the patch name argument to linkstg:push[] and
+linkstg:pop[]. If you do, you will push the next unapplied patch, and
pop the topmost patch, respectively.
NOTE: There are at least two more ways to update a non-topmost patch.
-One is to use stglink:refresh[] with the +$$--patch$$+ flag, the other
+One is to use linkstg:refresh[] with the +$$--patch$$+ flag, the other
to create a new patch for the update and then merge it into the other
-patch with stglink:squash[].
+patch with linkstg:squash[].
Keeping commit messages up to date
Since StGit is all about creating readable Git history (or a readable
patch series, which is essentially the same thing), one thing you'll
want to pay attention to is the commit messages of your patches.
-stglink:new[] asks you for a commit message when you create a new
+linkstg:new[] asks you for a commit message when you create a new
patch, but as time goes by and you refresh the patch again and again,
chances are that the original commit message isn't quite correct
anymore. Fortunately, editing the commit message is very easy:
$ stg edit <patch-name>
-In addition to stglink:edit[], you can also give the +$$--edit$$+ flag
-to stglink:refresh[] -- that way, you get to change the commit message
+In addition to linkstg:edit[], you can also give the +$$--edit$$+ flag
+to linkstg:refresh[] -- that way, you get to change the commit message
and update the patch at the same time. Use whichever feels most
natural to you.
-NOTE: stglink:edit[] has a +$$--diff$$+ flag, which gives you the diff
+NOTE: linkstg:edit[] has a +$$--diff$$+ flag, which gives you the diff
text and not just the commit message in your editor. Be aware, though,
that if you change the diff so that it no longer applies, the edit
will be saved to a file instead of being carried out. If you're not
'see' the diff while you edit the commit message.
If the patch changes considerably, it might even deserve a new name.
-stglink:rename[] is your friend there.
+linkstg:rename[] is your friend there.
Conflicts
StGit is telling us that it couldn't figure out how to push +first+ on
top of +second+, now that they both modify +TODO+. We can take a look
-at the situation with stglink:status[]:
+at the situation with linkstg:status[]:
$ stg status
? TODO.ancestor
? TODO.patched
C TODO
-As we were told by stglink:push[], the conflict is in the file +TODO+.
+As we were told by linkstg:push[], the conflict is in the file +TODO+.
(If the patch was bigger and touched multiple files, they would all be
listed here; prefixed with +C+ if they had conflicts, and +M+ if StGit
managed to automatically resolve everything in the file.)
At this point, we have two options:
- 1. Undo the failed merge with stglink:undo[]. (Remember to use the
+ 1. Undo the failed merge with linkstg:undo[]. (Remember to use the
+$$--hard$$+ flag, since the unresolved conflict means the
worktree is not clean.)
Now that we've resolved the conflict, we just need to tell StGit about
it:
- $ stg resolved TODO
+ $ git add TODO
$ stg status
M TODO
+ fix-documentation-error # Fix documentation error
> more-snarfle-cache # More snarfle cache
-As you can see, stglink:uncommit[] adds StGit metadata to the last few
+As you can see, linkstg:uncommit[] adds StGit metadata to the last few
Git commits, turning them into StGit patches so that we can do stuff
with them.
-NOTE: With the +$$--number$$+ flag, stglink:uncommit[] uncommits that
+NOTE: With the +$$--number$$+ flag, linkstg:uncommit[] uncommits that
many commits and generates names for them based on their commit
messages. If you like, you can instead list the patch names you want
on the command line.
At this point, there are a number of things we could do:
- * Continue developing, and take advantage of e.g. stglink:goto[] or
+ * Continue developing, and take advantage of e.g. linkstg:goto[] or
+stg refresh $$--patch$$+ to stick updates in the right patch to
begin with.
- * Use e.g. stglink:float[], stglink:sink[], stglink:push[], and
- stglink:pop[] to reorder patches.
+ * Use e.g. linkstg:float[], linkstg:sink[], linkstg:push[], and
+ linkstg:pop[] to reorder patches.
- * Use stglink:squash[] to merge two or more patches into one.
- stgsublink:squash[] pushes and pops so that the patches to be
+ * Use linkstg:squash[] to merge two or more patches into one.
+ linkstgsub:squash[] pushes and pops so that the patches to be
merged are consecutive and unrelated patches aren't in the way,
then makes one big patch out of the patches to be merged, and
finally pushes the other patches back.
$ stg commit --all
-TIP: stglink:commit[] can also commit specific patches (named on the
+TIP: linkstg:commit[] can also commit specific patches (named on the
command line), leaving the rest alone. This can be used to retire
patches as they mature, while keeping the newer and more volatile
patches as patches.
We've already covered how to clone a Git repository and start writing
patches. As for the next step, there are two commands you might use to
-get patches out of StGit: stglink:mail[] and stglink:export[].
-stglink:export[] will export your patches to a filesystem directory as
+get patches out of StGit: linkstg:mail[] and linkstg:export[].
+linkstg:export[] will export your patches to a filesystem directory as
one text file per patch, which can be useful if you are going to send
the patches by something other than e-mail. Most of the time, though,
-stglink:mail[] is what you want.
+linkstg:mail[] is what you want.
NOTE: Git comes with tools for sending commits via e-mail. Since StGit
patches are Git commits, you can use the Git tools if you like them
better for some reason.
NOTE: For exporting single patches -- as opposed to a whole bunch of
-them -- you could also use stglink:show[] or stglink:diff[].
+them -- you could also use linkstg:show[] or linkstg:diff[].
Mailing a patch is as easy as this:
message as subject line. Try mailing patches to yourself to see what
the result looks like.
-NOTE: stglink:mail[] uses +sendmail+ on your computer to send the
+NOTE: linkstg:mail[] uses +sendmail+ on your computer to send the
mails. If you don't have +sendmail+ properly set up, you can instruct
it to use any SMTP server with the +$$--smtp-server$$+ flag.
This will update all your remote branches, but won't touch your local
branches. To get the latest changes into your local +master+ branch,
-use stglink:rebase[]:
+use linkstg:rebase[]:
$ stg rebase remotes/origin/master
The primary reason for rebasing is to reduce the amount of conflicts
between your work and others'. If one of your patches changes the same
part of the same file as a patch someone else has written, you will
-get a conflict when you run stglink:rebase[] the next time after the
+get a conflict when you run linkstg:rebase[] the next time after the
other person's patch has been accepted upstream. It is almost always
less work to rebase often and resolve these one at a time, rather than
a whole lot at once. After all, you have to rebase eventually; if you
If and when some or all of your patches are accepted upstream, you
update and rebase just like usual -- but be sure to use the
-+$$--merged$$+ flag to stglink:rebase[]:
++$$--merged$$+ flag to linkstg:rebase[]:
$ git remote update
$ stg rebase --merged remotes/origin/master
The patches that had been merged will still be present in your patch
stack after the rebase, but they will be empty, since the change they
-added is now already present in the stack base. Run stglink:clean[] to
+added is now already present in the stack base. Run linkstg:clean[] to
get rid of such empty patches if you don't want them hanging around:
$ stg clean
StGit is. In that case, she'll probably apply your patches with
something like +git am+, and everything will just work, exactly as if
you'd used Git to send those patches. But she might be an StGit user
-too, in which case she might use stglink:import[].
+too, in which case she might use linkstg:import[].
There are basically four kinds if stuff you can import with
-stglink:import[]:
+linkstg:import[]:
1. A patch in a file.
~~~~~~~~~~~~~~~~~~~~~~~
Importing a plain patch, such as produced by e.g. GNU +diff+, +git
-diff+, +git show+, stglink:diff[], or stglink:show[], is very easy.
+diff+, +git show+, linkstg:diff[], or linkstg:show[], is very easy.
Just say
$ stg import my-patch
and you'll have a new patch at the top of your stack.
-If you don't give a file name on the command line, stglink:import[]
+If you don't give a file name on the command line, linkstg:import[]
will read the patch from its standard input -- in other words, you can
pipe a patch to it directly from the command that produces it.
Importing several patches at once
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Some programs -- among them stglink:export[] -- will create a bunch of
+Some programs -- among them linkstg:export[] -- will create a bunch of
files with one patch in each, and a 'series' file (often called
+series+) listing the other files in the correct order. Give
-+$$--series$$+ and the name of the series file to stglink:import[],
++$$--series$$+ and the name of the series file to linkstg:import[],
and it will import all the patches for you, in the correct order.
$ stg import --mail my-mail
The e-mail should be in standard Git mail format (which is what e.g.
-stglink:mail[] produces) -- that is, with the patch in-line in the
+linkstg:mail[] produces) -- that is, with the patch in-line in the
mail, not attached. The authorship info is taken from the mail
headers, and the commit message is read from the 'Subject:' line and
the mail body.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Finally, in case importing one patch at a time is too much work,
-stglink:import[] also accepts an entire Unix +mbox+-format mailbox,
+linkstg:import[] also accepts an entire Unix +mbox+-format mailbox,
either on the command line or on its standard input; just use the
+$$--mbox$$+ flag. Each mail should contain one patch, and is imported
just like with +$$--mail$$+.
-Mailboxes full of patches are produced by e.g. stglink:mail[] with the
+Mailboxes full of patches are produced by e.g. linkstg:mail[] with the
+$$--mbox$$+ flag, but most mail readers can produce them too, meaning
that you can copy all the patch mails you want to apply to a separate
mailbox, and then import them all in one go.
apply your changes to a tree not managed by Git, or send your changes
to someone else in e-mail, you need to convert your StGit patches into
normal textual diffs that can be applied with the GNU patch command.
-stglink:diff[] is a powerful way to generate and view textual diffs of
+linkstg:diff[] is a powerful way to generate and view textual diffs of
patches managed by StGit.
To view a diff of the topmost patch:
$ stg diff -r /
Observe that this does not show any changes in the working directory
-that have not been saved by a stgsublink:refresh[]. To view just the
+that have not been saved by a linkstgsub:refresh[]. To view just the
changes you've made since the last refresh, use:
$ stg diff -r /top
$ stg diff -r base
-stglink:diff[] supports a number of other features that are very
+linkstg:diff[] supports a number of other features that are very
useful. Be sure to take a look at the help information for this
command. To convert your StGit patches into patch files:
$ stg export [--range=[<patch1>[:<patch2>]]] [<dir-name>]
-stglink:export[] supports options to automatically number the patches
+linkstg:export[] supports options to automatically number the patches
(+-n+) or add the +.diff+ extension (+-d+). If you don't tell
-stgsublink:export[] where to put the patches, it will create directory
+linkstgsub:export[] where to put the patches, it will create directory
named +patch-<branchname>+ in your current directory, and store the
patches there. To e-mail a patch or range of patches:
$ stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>)
-stglink:mail[] has a lot of options, so read the output of +stg mail
+linkstg:mail[] has a lot of options, so read the output of +stg mail
-h+ for more information.
You can also import an existing GNU diff patch file as a new StGit
-patch with a single command. stglink:import[] will automatically parse
+patch with a single command. linkstg:import[] will automatically parse
through the patch file and extract a patch description. Use:
$ stg import [<file>]
$ stg refresh -e
Sometimes the patch file won't apply cleanly. In that case,
-stglink:import[] will leave you with an empty StGit patch, to which
+linkstg:import[] will leave you with an empty StGit patch, to which
you then apply the patch file by hand using "patch -i" and your
favorite editor.
TODO:: This section needs revising. I've only fixed the formatting.
-stglink:export[] and stglink:mail[] use templates for generating the
+linkstg:export[] and linkstg:mail[] use templates for generating the
patch files or e-mails. The default templates are installed under
+<prefix>/share/stgit/templates/+ and, combined with the extra options
available for these commands, should be enough for most users. The
template format uses the standard Python string formatting rules. The
variables available are listed in the the manual pages for each
-command. stglink:mail[] can also send an initial 'cover' e-mail for
+command. linkstg:mail[] can also send an initial 'cover' e-mail for
which there is no default template. The
+<prefix>/share/stgit/examples/firstmail.tmpl+ file can be used as an
example. A default description for new patches can be defined in the
~mdw / stgit / blobdiff