+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
+=========================
+
+
+Rebasing a patch series
+-----------------------
+
+TODO:: rebase, ...
+
+
+Getting patches upstream
+------------------------
+
+TODO:: export, mail, ...