##############
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.current
- ? 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.)
-NOTE: +TODO.ancestor+, +TODO.current+, and +TODO.patched+ are the
-three versions of the file that StGit tried to merge. The +.current+
-file is the version before the patch was applied, +.patched+ is the
-version in the patch we tried to push, and +.ancestor+ the version
-that contains neither of the added lines.
-
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.)
- 2. Manually resolve the conflict.
+ 2. Manually resolve the conflict (editing the file directly followed
+ by +git add+ or using +git mergetool+.)
To resolve the conflict, open +TODO+ in your favorite editor. It ends
like this:
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
+.git/ patchdescr.tmpl+ file. This is useful for things like
signed-off-by lines.
+
+Emacs
+=====
+
+StGit comes with an Emacs mode, +stgit-mode+, supporting Emacs
+versions 22 and later.
+
+To start using it, add the +stgit/contrib+ directory to your Emacs
+load-path and run +(require 'stgit)+. For example, you can add the
+following to your +.emacs+ file:
+
+----------------------------------------------------------------------
+(add-to-list 'load-path "/path/to/stgit/contrib")
+(require 'stgit)
+----------------------------------------------------------------------
+
+Start +stgit-mode+ using +M-x stgit+ and select the directory where
+the source code you want to use StGit on can be found. If StGit has
+not been initialized in this directory yet, you will need to run +M-x
+stgit-init+ before you continue.
+
+The +stgit-mode+ buffer (usually named +$$*stgit*$$+) has the
+following layout:
+
+----------------------------------------------------------------------
+Branch: name-of-branch
+
++ The first applied patch
++ Another applied patch
+> The topmost patch
+ Index
+ <no files>
+ Work Tree
+ <no files>
+- An unapplied patch
+- Another unapplied patch
+--
+----------------------------------------------------------------------
+
+The above means that the active branch name is +name-of-branch+ and it
+contains five patches, three of which are applied. The git index and
+working tree contain no (modified) files.
+
+Basic Commands
+--------------
+
+To get help, press +h+. This opens a new buffer which lists all
+commands supported in +stgit-mode+. Also, if you have the menu bar
+enabled (toggled using +M-x menu-bar-mode+), a new menu entry called
++StGit+ will appear, from which you can run several StGit commands. As
+the menu should be self-explanatory, the rest of this tutorial will
+focus on available keyboard commands.
+
+Move the point (cursor) between lines using +C-p+ and +C-n+, or
+between patches using +p+ and +n+.
+
+You can linkstgsub:undo[] and linkstgsub:redo[] StGit commands using
++C-/+ and +C-c C-/+, respectively.
+
+Creating New Patches
+--------------------
+
+If you want to create a new patch, first make some changes that should
+go into it. As you save a file which is Git-controlled, it will appear
+as a modification in the +Work Tree+ section:
+
+----------------------------------------------------------------------
+ Work Tree
+ Modified foo.txt
+----------------------------------------------------------------------
+
+To create a new patch based on the changes in the index or, if it
+contains no changes, the working tree, press +c+. This opens a new
+buffer where you can enter the patch description. When you are done,
+press +C-c C-c+. Your new patch will now show up in the +$$*stgit*$$+
+buffer, and the working tree will no longer contain any modifications:
+
+----------------------------------------------------------------------
++ The topmost patch
+> First line of your new description
+ Index
+ <no files>
+ Work Tree
+ <no files>
+----------------------------------------------------------------------
+
+As you make additional changes in your files, and want to include them
+in the topmost patch, press +r+, which runs linkstg:refresh[]. If you
+want to add the changes to a patch which is not topmost, move the
+point to the line of that patch and press +C-u r+.
+
+Inspecting Patches
+------------------
+
+To see what a particular patch contains, you can move the point
+(cursor) to the line of that patch, and press +RET+ (Enter). This will
+"expand" the patch and show which files it changes:
+
+----------------------------------------------------------------------
++ My patch
+ Modified foo.txt
+ Deleted bar.c
+----------------------------------------------------------------------
+
+You can press +=+, which will show the diff of that patch or file in a
+new buffer. With a prefix argument (+C-u =+), the diff will not show
+changes in whitespace.
+
+To visit (open) a modified file in another Emacs window, press +o+ on
+that line. +RET+ will visit it in the current window.
+
+Changing the Patch Series
+-------------------------
+
+You can linkstgsub:push[] and linkstgsub:pop[] patches using +>+
+(pushes the topmost unapplied patch onto the stack) and +<+ (pops the
+topmost applied patch off the stack).
+
+By moving the point to a particular patch and pressing +P+ (+S-p+)
+you either (if it already was applied) pop that patch off the stack,
+or (if it was unapplied) push it onto the stack.
+
+You can move patches by first marking one or more using +m+. Then,
+move the point to where in the series you want these patches to move,
+and press +M+. Use +DEL+ or +u+ to remove a mark.
+
+You can also combine (linkstgsub:squash[]) two or more patches by
+marking them and pressing +S+ (+S-s+). This will open a new buffer
+where you can edit the patch description of the new, combined, patch.
+When done, press +C-c C-c+, and the topmost of the marked patches will
+be replaced in the stack by one combined patch.
+
+You can linkstgsub:delete[] a patch by moving to its line and pressing
++D+. If you press +C-u D+, the contents of the patch will be spilled
+to the index.
+
+To linkstgsub:edit[] the description of a patch, press +e+. This opens
+the patch description in a new buffer. Press +C-c C-c+ when you are
+done editing the patch.
+
+These operations may result in merge conflicts; more about that later.
+
+Patch Names
+-----------
+
+By default, the patch description is shown but not the patch names.
+You can toggle showing the names using +t n+. To rename a patch, press
++C-c C-r+.
+
+Using the Index and Working Tree
+--------------------------------
+
+You can move a changed file between the index and the working tree
+using +i+. This is useful if your working tree contains a number of
+changes and you want to create or refresh a patch using only some of
+the changed file. Once you have the correct set of files in the index,
+use +c+ to create or +r+ to refresh patches using only the files in
+the index.
+
+If you want to revert a change in either the index or the working
+tree, move the point to that line and press +U+. If you press +U+ on
+the +Index+ or +Work Tree+ lines, all the changes in the index or
+working tree will be reverted.
+
+Branches
+--------
+
+You can switch to another linkstgsub:branch[] by pressing +B+. If you
+type the name of a branch that does not exist, you will be asked
+whether to create one. The new branch will be based off the current
++HEAD+.
+
+Use +C-c C-b+ to linkstgsub:rebase[] the current branch. It will
+default to rebasing to the +git config+ setting for
++branch._branch_.stgit.parentbranch+.
+
+Merge Conflicts
+---------------
+
+If an operation resulted in a merge conflict, the files with conflicts
+will show as +Unmerged+ in the +$$*stgit*$$+ buffer.
+
+To handle the conflicts, you can linkstgsub:undo[] the operation that
+caused the conflict using +C-u C-/+. Note the +C-u+ prefix, which will
+tell the undo operation to continue despite the index or working tree
+containing changes.
+
+If you instead want to resovle the changes, you must first edit the
+files with conflicts to make sure they are in the correct state. Once
+you have done this, press +R+ on the line of that file, which will
+remove the +Unmerged+ flag. Once all conflicts have been resolved, you
+can continue working as normal, for example by refreshing the patch
+that had the conflict.
+
+To investigate the reason of conflicts, you can use the +d b+, +d o+,
+and +d t+ commands to, respectively, show the diffs against the merge
+base, our branch, or their branch. +d c+ shows a combined diff. See
+linkman:git-diff[1] for more information about these commands.
+
+A more powerful tool to resolve conflicts is the Emacs +smerge-mode+.
+To start using it to resolve a conflict, press +d m+. It is outside
+the scope of this tutorial to explain how to use it, but press +q+ to
+leave +smerge-mode+.
~mdw / stgit / blobdiff