+ diff --git a/stgit/main.py b/stgit/main.py
+ index e324179..6398958 100644
+ --- a/stgit/main.py
+ +++ b/stgit/main.py
+ @@ -171,6 +171,7 @@ def _main():
+ sys.exit(ret or utils.STGIT_SUCCESS)
+
+ def main():
+ + print 'My first patch!'
+ try:
+ _main()
+ finally:
+
+(I'm assuming you're already familiar with
+htmllink: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[].
+
+Creating another patch
+----------------------
+
+We want to make another improvement, so let's create a new patch for
+it:
+
+ $ echo 'Audrey U. Thor' > AUTHORS
+ $ stg new credit --message 'Give me some credit'
+ $ 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
+the files.
+
+So now we have two patches:
+
+ $ stg series --description
+ + my-first-patch # This is my first patch
+ > credit # Give me some credit
+
+stglink: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+
+patch, so that +my-first-patch+ becomes topmost again:
+
+ $ stg pop credit
+ Checking for changes in the working directory ... done
+ Popping patch "credit" ... done
+ Now at patch "my-first-patch"
+ $ stg series --description
+ > 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
+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
+restored:
+
+ $ stg push credit
+ Checking for changes in the working directory ... done
+ 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
+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
+to create a new patch for the update and then merge it into the other
+patch with stglink:coalesce[].
+
+
+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
+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
+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
+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
+comfortable editing diffs, just treat +$$--diff$$+ as a way to get to
+'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.
+
+
+Conflicts
+---------
+
+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:
+
+ $ stg clone http://homepage.ntlworld.com/cmarinas/stgit.git stgit
+ $ cd stgit
+ $ stg new first --message 'First patch'
+ $ echo '- Do something' >> TODO
+ $ stg refresh
+ $ stg new second --message 'Second patch'
+ $ echo '- Install something' >> INSTALL
+ $ stg refresh
+
+then pop them both:
+
+ $ stg pop --all
+
+and then push them in the opposite order:
+
+ $ stg push second first
+ $ stg series
+ + second
+ > first
+
+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.
+
+ $ stg pop
+ Checking for changes in the working directory ... done
+ Popping patch "first" ... done
+ Now at patch "second"
+ $ echo '- Do something else' >> TODO
+ $ stg refresh
+
+Now, both patches add a new line at the end of +TODO+. So what happens
+when we try to have them both applied?
+
+ $ stg push
+ Pushing patch "first" ...
+ CONFLICT (content): Merge conflict in TODO
+ Error: The merge failed during "push".
+ Revert the operation with "stg undo".
+ stg push: 1 conflict(s)
+
+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[]:
+
+ $ stg status
+ ? TODO.ancestor
+ ? TODO.current
+ ? TODO.patched
+ C TODO
+
+As we were told by stglink: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
+ +$$--hard$$+ flag, since the unresolved conflict means the
+ worktree is not clean.)
+
+ 2. Manually resolve the conflict.
+
+To resolve the conflict, open +TODO+ in your favorite editor. It ends
+like this:
+
+----------------------------------------------------------------------
+- numeric shortcuts for naming patches near top (eg. +1, -2)
+- (config?) parameter for number of patches included by "series -s"
+<<<<<<< current:TODO
+- Do something else
+=======
+- Do something
+>>>>>>> patched:TODO
+----------------------------------------------------------------------
+
+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:
+
+----------------------------------------------------------------------
+- numeric shortcuts for naming patches near top (eg. +1, -2)
+- (config?) parameter for number of patches included by "series -s"
+- Do something
+- Do something else
+----------------------------------------------------------------------
+
+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:
+
+ $ stg resolved TODO
+ $ stg status
+ M TODO
+
++TODO+ is listed as being modified, not in conflict. And we know from
+before how to deal with modified files:
+
+ $ stg refresh
+
+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:
+
+ $ stg show
+ commit 8e3ae5f6fa6e9a5f831353524da5e0b91727338e
+ Author: Audrey U. Thor <author@example.com>
+ Date: Sun Oct 5 14:43:42 2008 +0200
+
+ First patch
+
+ diff --git a/TODO b/TODO
+ index 812d236..4ef3841 100644
+ --- a/TODO
+ +++ b/TODO
+ @@ -24,4 +24,5 @@ The future, when time allows or if someone else does them:
+ they have scripts for moving the changes in one to the others)
+ - numeric shortcuts for naming patches near top (eg. +1, -2)
+ - (config?) parameter for number of patches included by "series -s"
+ +- Do something
+ - Do something else
+
+
+Workflow: Development branch
+============================
+
+One common use of StGit is to ``polish'' a Git branch before you
+publish it for others to see. Such history falsification can often be
+a 'good' thing -- when you (or someone else) needs to look at what you
+did six months later, you are not really interested in all the false
+starts and the steps needed to corect them. What you want is the final
+solution, presented in a way that makes it easy to read and
+understand.
+
+Of course, there are limits. Editing the last few days' worth of
+history is probably a good idea; editing the last few months' probably
+isn't. A rule of thumb might be to not mess with history old enough
+that you don't remember the details anymore. And rewriting history
+that you have published for others to see (and base their own work on)
+usually just makes everyone more confused, not less.
+
+So, let's take a concrete example. Say that you're hacking on StGit,
+and have made several Git commits as your work progressed, with commit
+messages such as ``Improve the snarfle cache'', ``Remove debug
+printout'', ``New snarfle cache test'', ``Oops, spell function name
+correctly'', ``Fix documentation error'', and ``More snarfle cache''.
+
+Now, this is the actual history, but for obvious reasons, this isn't
+the kind of history you'd ideally want to find when you six months
+from now try to figure out exactly where that elusive snarfle cache
+bug was introduced. So let's turn this into the history we can be
+proud of. The first step is to make StGit patches out of all those Git
+commits:
+
+ $ stg uncommit --number 6
+ Uncommitting 6 patches ...
+ Now at patch "more-snarfle-cache"
+ done
+ $ stg series --description
+ + improve-the-snarfle-cache # Improve the snarfle cache
+ + remove-debug-printout # Remove debug printout
+ + new-snarfle-cache-test # New snarfle cache test
+ + oops-spell-function-name-corre # Oops, spell function name correctly
+ + 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
+Git commits, turning them into StGit patches so that we can do stuff
+with them.
+
+NOTE: With the +$$--number$$+ flag, stglink: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
+ +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 stglink:coalesce[] to merge two or more patches into one.
+ stgsublink:coalesce[] 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.
++
+Of course, as always when there is pushing involved, there is the
+possibility of conflicts. If a push results in a conflict, the
+operation will be halted, and we'll be given the option of either
+resolving the conflict or undoing.
+
+Once we feel that the history is as good as it's going to get, we can
+remove the StGit metadata, turning the patches back into regular Git
+commits again:
+
+ $ stg commit --all
+
+TIP: stglink: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.
+
+
+Workflow: Tracking branch
+=========================
+
+In the 'Development branch' workflow described above, we didn't have
+to worry about other people; we're working on our branch, they are
+presumably working on theirs, and when the time comes and we're ready
+to publish our branch, we'll probably end up merging our branch with
+those other peoples'. That's how Git is designed to work.
+
+Or rather, one of the ways Git is designed to work. An alternative,
+popular in e.g. the Linux kernel community (for which Git was
+originally created), is that contributors send their patches by e-mail
+to a mailing list. Others read the patches, try them out, and provide
+feedback; often, the patch author is asked to send a new and improved
+version of the patches. Once the project maintainer is satisfied that
+the patches are good, she'll 'apply' them to a branch and publish it.
+
+StGit is ideally suited for the process of creating patches, mailing
+them out for review, revising them, mailing them off again, and
+eventually getting them accepted.
+
+
+Getting patches upstream
+------------------------