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
(add-to-list 'load-path "/path/to/stgit/contrib") (require 'stgit)
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
before you continue.
stgit-mode buffer (usually named
*stgit*) has the following
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.
To get help, press
h. This opens a new buffer which lists all commands
stgit-mode. Also, if you have the menu bar enabled
M-x menu-bar-mode), a new menu entry called
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-n, or between
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,
C-c C-c. Your new patch will now show up in the
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 stg
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
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
RET will visit it in the current window.
Changing the Patch Series
By moving the point to a particular patch and pressing
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
u to remove a mark.
You can also combine (squash) two or more patches by
marking them and pressing
S-s). This will open a new buffer where
you can edit the patch description of the new, combined, patch. When
C-c C-c, and the topmost of the marked patches will be
replaced in the stack by one combined patch.
You can delete a patch by moving to its line and
D. If you press
C-u D, the contents of the patch will be
spilled to the index.
To edit the description of a patch, press
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.
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
Showing Committed Patches
Sometimes it is convenient to be able to investigate already committed
patches. Toggle showing these using
t h. With a prefix argument, you
can set how many to show; e.g.,
7 t h will show seven already
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
files. Once you have the correct set of files in the index, use
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
Work Tree lines, all the changes in the index or working
tree will be reverted.
You can switch to another branch by pressing
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
C-c C-b to rebase the current branch. It will
default to rebasing to the
git config setting for
If an operation resulted in a merge conflict, the files with conflicts
will show as
Unmerged in the
To handle the conflicts, you can 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 resolve 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
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 t commands to, respectively, show the diffs against the merge
base, our branch, or their branch.
d c shows a combined diff. See
git-diff(1) for more information
about these commands.
A more powerful tool to resolve conflicts is the Emacs
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