StGit tutorial

Now we’re ready to create our first patch:

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 stg show will tell you:

But it won’t stay that way for long! Open one of the files in your favorite text editor, change something, and save. You now have some local changes in your tree:

Then refresh the patch:

And voilà — the patch is no longer empty:

(I’m assuming you’re already familiar with 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 linkman:gitk[].

We want to make another improvement, so let’s create a new patch for it:

Note that we can give the commit message on the command line, and that it doesn’t matter whether we run stg new before or after we edit the files.

So now we have two patches:

stg 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 pop the credit patch, so that my-first-patch becomes topmost again:

stg series now shows that my-first-patch is topmost again, which means that stg 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 linkman:gitk[] will not show it, because it’s been edited out of the Git history. But it’s just one stg push command away from being restored:

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. stg 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:

In addition to stg edit, you can also give the --edit flag to stg 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.

If the patch changes considerably, it might even deserve a new name. stg rename is your friend there.

Normally, when you pop a patch, change something, and then later push it again, StGit sorts out everything for you automatically. For example, let’s create two patches that modify different files:

then pop them both:

and then push them in the opposite order:

StGit had no problems reordering these patches for us, since they didn’t touch the same file. But it would have worked just fine even if they had touched the same file, as long as they didn’t change the same part of the file. But what if they did? Let’s find out.

Now, both patches add a new line at the end of TODO. So what happens when we try to have them both applied?

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 stg status:

As we were told by stg 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:

To resolve the conflict, open TODO in your favorite editor. It ends like this:

The conflict markers <<<<<<<, =======, and >>>>>>> indicate which lines were already there (current) and which were added by the patch (patched). Edit the file so that it looks like it should; in this case, we want something like this:

Note that “looks like it should” includes removing the conflict markers.

Now that we’ve resolved the conflict, we just need to tell StGit about it:

TODO is listed as being modified, not in conflict. And we know from before how to deal with modified files:

The conflict is now resolved. We can see that first now looks a little different; it no longer adds a line at the end of the file:

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: stg mail and stg export. stg 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, stg mail is what you want.

Mailing a patch is as easy as this:

You can list one or more patches, or ranges of patches. Each patch will be sent as a separate mail, with the first line of the commit message as subject line. Try mailing patches to yourself to see what the result looks like.

There are many command-line options to control exactly how mails are sent, as well as a message template you can modify if you want. The man page has all the details; I’ll just mention two more here.

--edit-cover will open an editor and let you write an introductory message; all the patch mails will then be sent as replies to this cover message. This is usually a good idea if you send more than one patch, so that reviewers can get a quick overview of the patches you sent.

--edit-patches will let you edit each patch before it is sent. You can change anything, but note that you are only editing the outgoing mail, not the patch itself; if you want to make changes to the patch, you probably want to use the regular StGit commands to do so. What this is useful for, though, is to add notes for the patch recipients:

While you are busy writing, submitting, and revising your patch series, other people will be doing the same thing. As a result, even though you started writing your patches on top of what was the latest history at the time, your stack base will grow ever more out of date.

When you clone a repository,

you initially get one local branch, master. You also get a number of remote branches, one for each branch in the repository you cloned. In the case of the StGit repository, these are remotes/origin/stable, remotes/origin/master, and remotes/origin/proposed. remotes means that it’s not a local branch, just a snapshot of a branch in another repository; and origin is the default name for the first remote repository (you can set up more; see the man page for git remote).

Right after cloning, master and remotes/origin/master point at the same commit. When you start writing patches, master will advance, and always point at the current topmost patch, but remotes/origin/master will stay the same because it represents the master branch in the repository you cloned from — your upstream repository.

Unless you are the only one working on the project, however, the upstream repository will not stay the same forever. New commits will be added to its branches; to update your clone, run

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 stg rebase:

This command will do three things:

The end result is that your patches are now applied on top of the latest version of 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 stg 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 mail out patches that are based on an outdated branch, everyone who tries to apply them has to resolve the conflicts instead. There are more effective ways to get popular.

While you are busy producing patches, there’s hopefully someone — the maintainer — at the other end who recieves them and applies them to her Git tree, which is then published for all (or parts of) the world to see.

It’s perfectly fine for this person to not have the foggiest idea what 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 stg import.

There are basically four kinds if stuff you can import with stg import:

As mentioned in the introduction, StGit stores modifications to your working tree in the form of Git commits. This means if you want to 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. stg diff is a powerful way to generate and view textual diffs of patches managed by StGit.

To view a diff of the topmost patch:

Observe that this does not show any changes in the working directory that have not been saved by a refresh. To view just the changes you’ve made since the last refresh, use:

If you want to see the changes made by the patch combined with any unsaved changes in the working directory, try:

You can also show the changes to any patch in your stack with:

Use this command to view all the changes in your stack up through the current patch:

stg 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 supports options to automatically number the patches (-n) or add the .diff extension (-d). If you don’t tell 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 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. stg import will automatically parse through the patch file and extract a patch description. Use:

This is the equivalent of

Sometimes the patch file won’t apply cleanly. In that case, stg 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.

To merge a GNU diff file (defaulting to the standard input) into the topmost patch:

This command supports a --threeway option which applies the patch onto the bottom of the topmost one and performs a three-way merge.

stg export and stg 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. stg 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.

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 undo and redo StGit commands using C-/ and C-c C-/, respectively.

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:

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:

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 C-u r.

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:

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.

You can push and 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 (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 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 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.

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.

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 committed patches.

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 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.

You can switch to another 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 rebase the current branch. It will default to rebasing to the git config setting for branch.branch.stgit.parentbranch.

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 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.