[StGit PATCH 0/6] Documentation updates

[StGit PATCH 0/6] Documentation updates

[Karl Hasselström]

We're approaching a new StGit release (yay!), and the docs are rather
outdated. This is an attempt to refresh the main stg man page and the
tutorial (but I ran out of time for this weekend, so the second half
of the tutorial is incomplete).

Comments & helping hands much appreciated.

Since I touch almost every line, the patches are kind of a nuisance to
read. It's probably easiest to just fetch the branch:

  git://repo.or.cz/stgit/kha.git doc

---

Karl Hasselström (6):
      Refresh and expand the tutorial (not finished)
      Refresh the main stg man page
      Add 1.0 TODO items from recent discussion by private mail
      We're half-way there with the separate indexes
      Remove TODO items that have already been addressed
      Remove unused variable


 Documentation/Makefile      |   11 -
 Documentation/asciidoc.conf |   22 +
 Documentation/stg.txt       |  150 +++++---
 Documentation/tutorial.txt  |  794 ++++++++++++++++++++++++++-----------------
 TODO                        |   26 +
 stgit/argparse.py           |    2 
 6 files changed, 603 insertions(+), 402 deletions(-)

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle

[StGit PATCH 1/6] Remove unused variable

[Karl Hasselström]

Signed-off-by: Karl Hasselström <kha@treskal.com>

---

 Documentation/Makefile |    8 +++-----
 1 files changed, 3 insertions(+), 5 deletions(-)


diff --git a/Documentation/Makefile b/Documentation/Makefile
index 165e222..37df9ee 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -5,12 +5,10 @@ MAN1_TXT= stg.txt $(COMMANDS_TXT)
 
 DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT))
 
-ARTICLES = 
-# with their own formatting rules.
-SP_ARTICLES = tutorial
+ARTICLES = tutorial
 
-DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
-DOC_PDF += $(patsubst %,%.pdf,$(ARTICLES) $(SP_ARTICLES))
+DOC_HTML += $(patsubst %,%.html,$(ARTICLES))
+DOC_PDF += $(patsubst %,%.pdf,$(ARTICLES))
 
 DOC_MAN1=$(patsubst %.txt,%.1,$(MAN1_TXT))
 

[StGit PATCH 2/6] Remove TODO items that have already been addressed

[Karl Hasselström]

Signed-off-by: Karl Hasselström <kha@treskal.com>

---

 TODO |    9 ---------
 1 files changed, 0 insertions(+), 9 deletions(-)


diff --git a/TODO b/TODO
index ff52a95..3570345 100644
--- a/TODO
+++ b/TODO
@@ -1,14 +1,9 @@
 The TODO list before 1.0:
 
 - more regression tests
-- stg help should probably pipe through the $PAGER
-- fix StGIT to run correctly in subdirectories
 - use a separate index for some commands (refresh, fold etc.) so that
   files already added/removed are not automatically checked in
-- debian package support
-- man page
 - document the workflow on the StGIT wiki
-- use same configuration file as GIT
 - release 1.0
 
 
@@ -18,9 +13,5 @@ The future, when time allows or if someone else does them:
 - multiple heads in a patch - useful for forking a patch,
   synchronising with other patches (diff format or in other
   repositories)
-- commit directly to a patch which is not top
-- patch synchronisation between between branches (as some people,
-  including me have the same patches based on different branches and
-  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"

[StGit PATCH 3/6] We're half-way there with the separate indexes

[Karl Hasselström]

Signed-off-by: Karl Hasselström <kha@treskal.com>

---

 TODO |    6 ++++++
 1 files changed, 6 insertions(+), 0 deletions(-)


diff --git a/TODO b/TODO
index 3570345..267e17e 100644
--- a/TODO
+++ b/TODO
@@ -1,8 +1,14 @@
 The TODO list before 1.0:
 
 - more regression tests
+
 - use a separate index for some commands (refresh, fold etc.) so that
   files already added/removed are not automatically checked in
+
+    + This is easily done with the new infrastructure. refresh now
+      uses a separate index when appropriate. fold has not yet been
+      converted.
+
 - document the workflow on the StGIT wiki
 - release 1.0
 

[StGit PATCH 4/6] Add 1.0 TODO items from recent discussion by private mail

[Karl Hasselström]

Signed-off-by: Karl Hasselström <kha@treskal.com>

---

 TODO |   11 ++++++++++-
 1 files changed, 10 insertions(+), 1 deletions(-)


diff --git a/TODO b/TODO
index 267e17e..a01daef 100644
--- a/TODO
+++ b/TODO
@@ -2,6 +2,16 @@ The TODO list before 1.0:
 
 - more regression tests
 
+- Convert the remaining commands to the new infrastructure.
+
+- Go through the design of the UI and make sure there's nothing hard
+  to change in there that we'll regret later.
+
+- Write a user guide. I'm thinking a document on the order of 10-30
+  pages that'll explain why one would want to use StGit, and how.
+
+- Make sure the rest of the documentation is in good shape.
+
 - use a separate index for some commands (refresh, fold etc.) so that
   files already added/removed are not automatically checked in
 
@@ -9,7 +19,6 @@ The TODO list before 1.0:
       uses a separate index when appropriate. fold has not yet been
       converted.
 
-- document the workflow on the StGIT wiki
 - release 1.0
 
 

[StGit PATCH 5/6] Refresh the main stg man page

[Karl Hasselström]

Update the text to reflect what's happened in StGit in the last few
releases. Also, consistently capitalize the names "Git" and "StGit".

Signed-off-by: Karl Hasselström <kha@treskal.com>

---

 Documentation/asciidoc.conf |   22 +++++-
 Documentation/stg.txt       |  150 +++++++++++++++++++++++++------------------
 stgit/argparse.py           |    2 -
 3 files changed, 107 insertions(+), 67 deletions(-)


diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 5f7a7af..f2c0ede 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -44,9 +44,23 @@ template::[header-declarations]
 endif::backend-docbook[]
 endif::doctype-manpage[]
 
-## link: macro
+## htmllink: macro
 #
-# Usage: link:command[manpage-section]
+# Usage: htmllink:url[text]
+
+ifdef::backend-docbook[]
+[htmllink-inlinemacro]
+{0}
+endif::backend-docbook[]
+
+ifdef::backend-xhtml11[]
+[htmllink-inlinemacro]
+<a href="{target}">{0}</a>
+endif::backend-xhtml11[]
+
+## manlink: macro
+#
+# Usage: manlink:command[manpage-section]
 #
 # Note, {0} is the manpage section, while {target} is the command.
 #
@@ -54,7 +68,7 @@ endif::doctype-manpage[]
 # show the command.
 
 ifdef::backend-docbook[]
-[link-inlinemacro]
+[manlink-inlinemacro]
 {0%{target}}
 {0#<citerefentry>}
 {0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
@@ -62,7 +76,7 @@ ifdef::backend-docbook[]
 endif::backend-docbook[]
 
 ifdef::backend-xhtml11[]
-[link-inlinemacro]
+[manlink-inlinemacro]
 <a href="{target}.html">{target}{0?({0})}</a>
 endif::backend-xhtml11[]
 
diff --git a/Documentation/stg.txt b/Documentation/stg.txt
index d8f7d01..9c6b267 100644
--- a/Documentation/stg.txt
+++ b/Documentation/stg.txt
@@ -1,11 +1,10 @@
 stg(1)
 ======
 Yann Dirson <ydirson@altern.org>
-v0.12.1, February 2007
 
 NAME
 ----
-stg - manage stacks of patches using the GIT content tracker
+stg - Manage stacks of patches using the Git content tracker
 
 SYNOPSIS
 --------
@@ -17,86 +16,113 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-StGIT (Stacked GIT) is an application providing similar functionality
-to Quilt (i.e. pushing/popping patches to/from a stack), on top of
-GIT. These operations are performed using GIT commands and the patches
-are stored as GIT commit objects, allowing easy merging of the StGIT
-patches into other repositories using standard GIT functionality.
+StGit (Stacked Git) is an application that provides a convenient way
+to maintain a 'patch stack' on top of a Git branch:
 
-An StGIT stack is a GIT branch with additional information to help
-making changes to individual patches you already committed, rather
-than making changes by adding new commits.  It is thus a
-non-forwarding, or rewinding branch: the old head of the branch is
-often not reachable as one of the new head's ancestors.
+  * The topmost (most recent) commits of a branch are given names.
+    Such a named commit is called a 'patch'.
 
-Typical uses of StGIT include:
+  * After making changes to the worktree, you can incorporate the
+    changes into an existing patch; this is called 'refreshing'. You
+    may refresh any patch, not just the topmost one.
+
+  * You can 'pop' a patch: temporarily putting it aside, so that the
+    patch below it becomes the topmost patch. Later you may 'push' it
+    onto the stack again. Pushing and popping can be used to reorder
+    patches.
+
+  * You can easily 'rebase' your patch stack on top of any other Git
+    branch. (The 'base' of a patch stack is the most recent Git commit
+    that is not an StGit patch.) For example, if you started making
+    patches on top of someone else's branch, and that person publishes
+    an updated branch, you can take all your patches and apply them on
+    top of the updated branch.
+
+  * The patch stack is just some extra metadata attached to regular
+    Git commits, so you can continue to use Git tools along with
+    StGit.
+
+Typical uses
+~~~~~~~~~~~~
 
 Tracking branch::
-	Tracking changes from a remote branch, while maintaining local
-	modifications against that branch, possibly with the intent of
-	sending some patches upstream.  StGIT assists in preparing and
-	cleaning up patches until they are acceptable upstream, as
-	well as maintaining local patches not meant to be sent
-	upstream.
+
+  Tracking changes from a remote branch, while maintaining local
+  modifications against that branch, possibly with the intent of
+  sending some patches upstream. You can modify your patch stack as
+  much as you want, and when your patches are finally accepted
+  upstream, the permanent recorded Git history will contain just the
+  final sequence of patches, and not the messy sequence of edits that
+  produced them.
 +
-In such a setup, typically all commits on your branch are StGIT
-patches; the stack base is the branch point where your changes "fork"
-off their parent branch.
+Commands of interest in this workflow are e.g. stgsublink:rebase[] and
+stgsublink:mail[].
 
 Development branch::
-	Preparing and testing your commits before publishing them,
-	separating your features from unrelated bugfixes collected
-	while developping.
+
+  Even if you have no "upstream" to send patches to, you can use StGit
+  as a convenient way to modify the recent history of a Git branch.
+  For example, instead of first committing change 'A', then change
+  'B', and then 'A2' to fix 'A' because it wasn't quite right, you
+  could incorporate the fix directly into 'A'. This way of working
+  results in a much more readable Git history than if you had
+  immortalized every misstep you made on your way to the right
+  solution.
 +
-In such a setup, not all commits on your branch need to be StGIT
-patches; there may be regular GIT commits below your stack base.
+Commands of interest in this workflow are e.g. stgsublink:uncommit[],
+which can be used to move the patch stack base downwards -- i.e., turn
+Git commits into StGit patches after the fact -- and
+stgsublink:commit[], its inverse.
+
+For more information, see htmllink:tutorial.html[the tutorial].
 
-Patches
-~~~~~~~
+Specifying patches
+~~~~~~~~~~~~~~~~~~
 
-Many StGIT commands take references to StGIT patches as arguments.
+Many StGit commands take references to StGit patches as arguments.
 Patches in the stack are identified with short names, each of which
 must be unique in the stack.
 
-Patches in the current stack are just referred to by their name.  Some
-commands allow you to specify a patch in another stack of the repository;
-this is done by suffixing the patch name with an '@' sign followed by the
-branch name (eg. 'thispatch@otherbranch').
+Patches in the current branch are simply referred to by their name.
+Some commands allow you to specify a patch in another branch of the
+repository; this is done by prefixing the patch name with the branch
+name and a colon (e.g. +otherbranch:thatpatch+).
+
+Specifying commits
+~~~~~~~~~~~~~~~~~~
+
+Some StGit commands take Git commits as arguments. StGit accepts all
+commit expressions that Git does; and in addition, a patch name
+(optionally prefixed by a branch name and a colon) is allowed in this
+context. The usual Git modifiers $$^$$ and $$~$$ are also allowed;
+e.g., +abranch:apatch~2+ is the grandparent of the commit that is the
+patch +apatch+ on branch +abranch+.
 
-A number of positions in the stack related to the patch are also
-accessible through '//' suffixes.  For example, 'patch//top' is
-equivalent to 'patch', and 'patch//bottom' refers to the commit below
-'patch' (i.e. the patch below, or the stack base if this is the
-bottom-most patch).  Similarly '//top.old' and '//bottom.old'
-refer to the previous version of the patch (before the last
-stglink:push[] or stglink:refresh[] operation).  When referring to the
-current patch, its name can be omitted (eg. 'currentpatch//bottom.old'
-can be abbreviated as 'bottom.old').
+Instead of a patch name, you can say +$${base}$$+ to refer to the
+stack base (the commit just below the bottommost patch); so,
++abranch:$${base}$$+ is the base of the stack in branch +abranch+.
 
-If you need to pass a given StGIT reference to a git command,
-stglink:id[] will convert it to a git commit id.
+If you need to pass a given StGit reference to a Git command,
+stglink:id[] will convert it to a Git commit id for you.
 
 OPTIONS
 -------
 
-The following generic option flags are available.  Additional options
-are available per-command, and documented in the command-specific
-documentation.
+The following generic option flags are available. Additional options
+are available for (and documented with) the different subcommands.
 
 --version::
-	Prints the StGIT suite version that the 'stg' program came
-	from, as well as version of other components used, such as GIT
-	and Python.
+  Prints the StGit version, as well as version of other components
+  used, such as Git and Python.
 
 --help::
-	Prints the synopsis and a list of all commands.  If a git
-	command is given this option will display the specific help
-	for that command.
+  Prints the synopsis and a list of all subcommands. If an StGit
+  subcommand is given, prints the synposis for that subcommand.
 
 STGIT COMMANDS
 --------------
 
-We divide StGIT commands in thematic groups, according to the primary
+We divide StGit commands in thematic groups, according to the primary
 type of object they create or change.
 
 ifdef::backend-docbook[]
@@ -110,16 +136,16 @@ include::command-list.txt[]
 CONFIGURATION MECHANISM
 -----------------------
 
-Starting with 0.12, StGIT uses the same configuration mechanism as
-GIT.  See link:git[7] for more details.
+StGit uses the same configuration mechanism as Git. See manlink:git[7]
+for more details.
 
 TEMPLATES
 ---------
 
-A number of StGIT commands make use of template files to provide
-useful default texts to be edited by the user.  These '<name>.tmpl'
+A number of StGit commands make use of template files to provide
+useful default texts to be edited by the user. These +<name>.tmpl+
 template files are searched in the following directories:
 
-	$GITDIR/
-	$HOME/.stgit/templates/
-	/usr/share/stgit/templates/
+  . +$GITDIR/+ (in practice, the +.git/+ directory in your repository)
+  . +$HOME/.stgit/templates/+
+  . +/usr/share/stgit/templates/+
diff --git a/stgit/argparse.py b/stgit/argparse.py
index 406ada3..0adb8ff 100644
--- a/stgit/argparse.py
+++ b/stgit/argparse.py
@@ -103,7 +103,7 @@ def write_asciidoc(cmd, f):
             o.write_asciidoc(f)
             f.write('\n')
     _write_underlined('StGit', '-', f)
-    f.write('Part of the StGit suite - see link:stg[1]\n')
+    f.write('Part of the StGit suite - see manlink:stg[1]\n')
 
 def sign_options():
     def callback(option, opt_str, value, parser, sign_str):

[StGit PATCH 6/6] Refresh and expand the tutorial (not finished)

[Karl Hasselström]

This is a first pass at expanding the tutorial, fixing its formatting,
and updating it with the new things that have happened in StGit.

There are a number of things still left to do in the second half of
the document; they are tagged with "TODO".

Signed-off-by: Karl Hasselström <kha@treskal.com>

---

 Documentation/Makefile     |    3 
 Documentation/tutorial.txt |  794 ++++++++++++++++++++++++++------------------
 2 files changed, 477 insertions(+), 320 deletions(-)


diff --git a/Documentation/Makefile b/Documentation/Makefile
index 37df9ee..dd029d5 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -82,6 +82,7 @@ command-list.txt: $(ALL_PY)
 
 # special formatting rules
 tutorial.html : %.html : %.txt
-	$(ASCIIDOC) -b xhtml11 -d article -f tutorial.conf $(ASCIIDOC_EXTRA) $<
+	$(ASCIIDOC) -b xhtml11 -d article -a toc -f tutorial.conf \
+                $(ASCIIDOC_EXTRA) $<
 tutorial.xml : %.xml : %.txt
 	$(ASCIIDOC) -b docbook -d article -f tutorial.conf $<
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index 472a5c3..103f3e4 100644
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -1,416 +1,572 @@
-StGIT Tutorial
+StGit tutorial
 ##############
 
+StGit is a command-line application that provides functionality
+similar to htmllink: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
+them in various ways.
 
-StGIT is a Python application that provides functionality similar to
-quilt (i.e. pushing/popping patches to/from a stack) using GIT instead
-of 'diff' and 'patch'. StGIT stores its patches in a GIT repository as
-normal GIT commit objects.
-StGIT is not an SCM interface on top of GIT. For standard SCM
-operations, either use GIT's porcelain commands or the Cogito tool.
-StGIT is available for download at http://www.procode.org/stgit/ .
-This tutorial assumes you are already familiar with GIT. For more
-information on GIT, see the GIT_tutorial or git(7) .
+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
+page].
 
 
-Basic Operation
+Help
+====
+
+For a full list of StGit commands:
+
+  $ stg help
+
+For quick help on individual subcommands:
+
+  $ stg help <cmd>
+
+For more extensive help on a subcommand:
+
+  $ man stg-<cmd>
+
+(The documentation is also available in htmllink:stg.html[HTML
+format].)
+
+
+Getting started
 ===============
 
-Help
-----
+StGit is not a stand-alone program -- it operates on a Git repository
+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
+  $ cd stgit
+
+Before you can create StGit patches, you have to run stglink:init[]:
+
+  $ stg init
 
-For a full list of StGIT commands:
+This initializes the StGit metadata for the current branch. (So if you
+want to have StGit patches in another branch too, you need to run +stg
+init+ again in that branch.)
 
-  stg help
+NOTE: As a shortcut, stglink:clone[] will run +git clone+ followed by
++stg init+ for you.
 
-For help on individual subcommands:
 
-  stg <cmd> (-h | --help)
+Creating a patch
+----------------
 
+Now we're ready to create our first patch:
 
-Repository initialisation
--------------------------
+  $ stg new my-first-patch
 
-In stand-alone mode, StGIT is used in conjunction with a GIT repository
-that is already initialised (using 'git init'). StGIT cannot be used
-outside of a GIT repository.
-Any branch in a GIT repository may be managed by StGIT. Each branch
-managed by StGIT contains an independent series of StGIT patches.
-To initialise an existing GIT branch to be managed by StGIT, cd into the
-top of your GIT repository, check out the branch you'd like to manage
-with StGIT, and type:
+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
+you:
 
-  stg init
+  $ stg show
 
-Run the 'stg init' command for any pre-existing GIT branches intended to
-be used with StGIT.
-You can switch between GIT branches with:
+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:
 
-  stg branch [<branch name>]
+  $ stg status
+  M stgit/main.py
 
-This checks out the named branch and places you at the topmost applied
-StGIT patch in that branch.
-Alternately, you can create branches using only StGIT commands, which
-will automatically prepare them for use with StGIT:
+Then stgsublink:refresh[] the patch:
 
-  stg branch --create <new branch>
+  $ stg refresh
 
+And voilà -- the patch is no longer empty:
 
-Working with remote repositories
---------------------------------
+  $ stg show
+  commit 3de32068c600d40d8af2a9cf1f1c762570ae9610
+  Author: Audrey U. Thor <author@example.com>
+  Date:   Sat Oct 4 16:10:54 2008 +0200
 
-With a single command, StGIT can create and initialize a GIT repository
-which mirrors a remote GIT repository. This is known as cloning. All GIT
-transports are supported.
-To clone a repository, use:
+      Tell the world that I've made a patch
 
-  stg clone <repository> <local-dir>
+  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)
 
-This creates a fresh local repository, initialises a GIT database in it,
-pulls the latest version of the remote, and creates and initialises a
-'master' branch for use with StGIT.
-At any time you can pull the latest changes from the remote repository.
-By default, StGIT pulls from the location stored in .git/branches/
-origin, and updates the base of the current branch.
-To pull the latest changes from a remote repository, use:
+   def main():
+  +    print 'My first patch!'
+       try:
+           _main()
+       finally:
 
-  stg pull [<branch> or 'origin']
+(I'm assuming you're already familiar with 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.)
 
-This command removes all applied StGIT patches from the current branch,
-updates the branch's base commit, then attempts to re-apply the patches.
-Any merge conflicts will halt this process, allowing you to clean up the
-conflicts and continue (see below).
-If the maintainer of the remote repository includes one of your patches
-in the published repository that you pull from, StGIT can usually
-recognize that an incoming patch from the remote matches one of yours,
-and it turns your local version into an empty patch.
-To automatically delete empty patches after a pull, use:
+Since the patch is also a regular Git commit, you can also look at it
+with regular Git tools such as manlink:gitk[].
 
-  stg clean
+Creating another patch
+----------------------
 
-As a convention, you should avoid working in the 'master' branch and use
-it only as a reference, since it reflects someone else's work. If you
-decide to publish your GIT repository, you'll want your own work
-separated into its own branch to make it convenient for others to pull
-just your patches.
+We want to make another improvement, so let's create a new patch for
+it:
 
-Getting started: creating a patch
----------------------------------
+  $ echo 'Audrey U. Thor' > AUTHORS
+  $ stg new credit --message 'Give me some credit'
+  $ stg refresh
 
-Changes to your working directory are saved in a patch. An StGIT patch
-is simply a saved set of modifications to your working directory, plus a
-saved description. To create an empty StGIT patch in the current branch:
+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.
 
-  stg new <name>
+So now we have two patches:
 
-To save the changes you've made (that is, to refresh a patch), use:
+  $ stg series --description
+  + my-first-patch # This is my first patch
+  > credit         # Give me some credit
 
-  stg refresh
+stglink:series[] lists the patches from bottom to top; +$$+$$+ means
+that a patch is 'applied', and +>+ that it is the 'current', or
+topmost, patch.
 
-To discard changes in your working directory, use:
+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:
 
-  git checkout -f
+  $ 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
 
-This restores your working directory to the state it was in the last
-time the patch was refreshed.
-Modified files that haven't been saved via a refresh operation can be
-viewed with:
+stglink:series[] now shows that +my-first-patch+ is topmost again,
+which means that stglink:refresh[] will update it with any changes we
+make.
 
-  stg status
+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:
 
-You can view modified files that have already been saved into a patch:
+  $ stg push credit
+  Checking for changes in the working directory ... done
+  Fast-forwarded patch "credit"
+  Now at patch "credit"
 
-  stg files
+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.
 
-The 'stg refresh' command automatically notes changes to files that
-already exist in the working directory (it also notices if you remove
-them), but you have to tell StGIT explicitly if you add or rename a
-file:
+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[].
 
-  git add new-file
 
-to add a file, and
+Keeping commit messages up to date
+----------------------------------
 
-  mv old-file new-file
-  git add new-file
+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:
 
-or simply
+  $ stg edit <patch-name>
 
-  git mv old-file new-file
+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.
 
-to move a file.
+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.
 
-Stack manipulation: managing multiple patches
----------------------------------------------
 
-StGIT can manage more than one patch at a time. A series of StGIT
-patches in a GIT branch are known collectively as a stack. The new patch
-you created above is now the topmost patch in your stack. You can always
-see the name of the topmost (current) patch with:
+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, ...
 
-  stg top
 
-The topmost patch is used as the default patch for most StGIT
-operations. It is the default target of the 'stg refresh' command, for
-example.
-Patches that are pushed onto the stack are referred to as applied, and
-patches that are popped off the stack are referred to as unapplied.
-To push/pop a patch to/from a stack:
+Importing patches
+-----------------
 
-  stg push [--all | <name>]
-  stg pop [--all]
+TODO:: import, ...
 
-The last patch you pushed is the topmost patch. This patch is always in
-the applied list; StGIT can't operate on an unapplied patch unless you
-apply it first.
-You can display the order of patches in a stack with one of these
-commands:
 
-  stg series
-  stg applied
-  stg unapplied
+Other stuff that needs to be placed somewhere
+=============================================
+
+
+Undo
+----
+
+TODO:: undo, redo, log, reset
 
-By default the 'stg push' command applies the first patch in the
-unapplied list, but you can push any patch in the unapplied list by
-giving the name of the patch. This is useful if you want to reorder the
-patches in a stack.
-During a push operation, merge conflicts can occur (especially if you
-are changing the order of the patches in your stack). If the push causes
-merge conflicts, they need to be fixed and 'stg resolved' run (see
-below). A 'push' operation can also be reverted with 'stg undo' (you
-will need to give it the --hard flag, since the conflicting push will
-have left your work tree dirty).
-A few more stack basics; to rename a patch:
 
-  stg rename <old-name> <new-name>
+Interoperating with Git
+-----------------------
 
-To delete a patch:
+TODO::
 
-  stg delete <name>
+* git commit + repair
 
-This permanently discards the named patch. In other words, the patch no
-longer appears in either the applied or unapplied lists, and cannot be
-reapplied to the series.
-You may want to make patches in your stack a permanent part of your GIT
-repository, for example if you are publishing your repository to others.
-To do this, use:
+* git reset HEAD~n + repair
 
-  stg commit
+* don't do git rebase or git merge, because it won't work
 
-This merges all applied patches in your patch series into the GIT
-repository and removes them from your stack. Use this command only if
-you want to permanently store the applied patches and no longer manage
-them with StGIT.
 
-Converting between StGIT patches and text diffs
------------------------------------------------
+Patch stuff
+-----------
+
+TODO:: This section needs revising. I've only fixed the formatting.
+Most of it should go under "Workflow: Tracking branch"
+
+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.
+stglink:diff[] is a powerful way to generate and view textual diffs of
+patches managed by StGit.
 
-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.
-The 'stg diff' command 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 /
+  $ stg diff -r /
 
 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:
+that have not been saved by a stgsublink:refresh[]. To view just the
+changes you've made since the last refresh, use:
 
-  stg diff -r /top
+  $ stg diff -r /top
 
 If you want to see the changes made by the patch combined with any
 unsaved changes in the working directory, try:
 
-  stg diff -r /bottom
+  $ stg diff -r /bottom
 
 You can also show the changes to any patch in your stack with:
 
-  stg diff -r <patch>/
+  $ stg diff -r <patch>/
 
 Use this command to view all the changes in your stack up through the
 current patch:
 
-  stg diff -r base
+  $ stg diff -r base
 
-The 'stg diff' command 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:
+stglink: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>]
+  $ stg export [--range=[<patch1>[:<patch2>]]] [<dir-name>]
 
-The 'export' command supports options to automatically number the
-patches (-n) or add the '.diff' extension (-d). If you don't tell "stg
-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:
+stglink: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
+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>)
+  $ stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>)
 
-"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:
+stglink:mail[] has a lot of options, so read the output of +stg mail
+-h+ for more information.
 
-  stg import [<file>]
+You can also import an existing GNU diff patch file as a new StGit
+patch with a single command. stglink:import[] will automatically parse
+through the patch file and extract a patch description. Use:
 
-This is the equivalent of "stg new" followed by "patch -i <file>", then
-"stg refresh -e".
-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:
+  $ stg import [<file>]
 
-  stg fold [<file>]
+This is the equivalent of
 
-This command supports a '--threeway' option which applies the patch onto
-the bottom of the topmost one and performs a three-way merge.
+  $ stg new
+  $ patch -i <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
+you then apply the patch file by hand using "patch -i" and your
+favorite editor.
 
-Advanced Usage
-==============
+To merge a GNU diff file (defaulting to the standard input) into the
+topmost patch:
 
-Handling merge conflicts
-------------------------
+  $ stg fold [<file>]
 
-Pushing a patch on the stack can fail if the patch cannot be applied
-cleanly. This usually happens if there are overlapping changes in the
-tree, the patch depends on another patch which is not applied, or if a
-patch was not merged upstream in the exact form it was sent.
-The 'push' operation stops after the first patch with conflicts. The
-'status' command shows the conflict files by marking them with a 'C'. If
-the 'keeporig' options is set to 'yes' (the default), the original files
-involved in the merge operations are left in the tree as <file>.older,
-<file>.local and <file>.remote for better analysis of the conflict. If
-'diff3' is used as the merger (the default), markers are added to the
-conflicted files as well.
-Run the 'resolved' command to mark the conflicts resolved and remove the
-temporary merge files from the working tree. Then run the 'refresh'
-command to update the StGIT patch with the modifications you made to
-resolve the conflict.
-
-
-Configuration file
-------------------
-
-StGIT tries to read the configuration options from the following files:
-/etc/stgitrc, ~/.stgitrc and .git/stgitrc. The latter overrides the
-options in the former files. If no file is found, the defaults are used.
-An example configuration file with options description can be found in
-the examples/ directory. Most users would probably only define the
-'smtpserver' option used by the 'mail' command.
-The gitmergeonefile.py script does the three-way merging on individual
-files using the tool specified by the 'merger' option. The user can
-specify a smarter tool to be used.
+This command supports a +$$--threeway$$+ option which applies the
+patch onto the bottom of the topmost one and performs a three-way
+merge.
 
 
 Templates
 ---------
 
-The 'export' and 'mail' commands 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 the commands, should be enough for most users. The template format
-uses the standard Python string formatting rules. The variables
-available are shown in the the help message for the commands.
-The 'mail' command can also send an initial 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.
-
-
-Merging two patches into one
-----------------------------
-
-There is no command to do this directly at the moment but one can export
-the patch to be merged and use the 'stg fold' command on the generated
-diff file. Assuming that the merged patch was not already applied, the
-operation will succeed. Pushing the merged patch onto the stack will
-result in an empty patch (StGIT notifying the user) that can be safely
-deleted.
-
-
-Technical Information
-=====================
-
-A bit of StGIT patch theory
----------------------------
-
-We assume that a patch is a diff between two nodes - bottom and top. A
-node is a commit SHA1 id or tree SHA1 id in the GIT terminology:
-
-  P - patch
-  N - node
-
-  P = diff(Nt, Nb)
-
-  	Nb - bottom (start) node
-  	Nt - top (end) node
-  	Nf - first node (for log generation)
-
-For an ordered stack of patches:
-
-  P1 = diff(N1, N0)
-  P2 = diff(N2, N1)
-  ...
-
-
-  Ps = P1 + P2 + P3 + ... = diff(Nst, Nsb)
-
-  	Ps  - the big patch of the whole stack
-  	Nsb - bottom stack node (= N0)
-  	Nst - top stack node (= Nn)
-
-Applying (pushing) a patch on the stack (Nst can differ from Nb) is done
-by diff3 merging. The new patch becomes:
-
-  P' = diff(Nt', Nb')
-  Nb' = Nst
-  Nt' = diff3(Nst, Nb, Nt)
-
-(note that the diff3 parameters order is: branch1, ancestor, branch2)
-The above operation allows easy patch re-ordering.
-Removing (popping) a patch from the stack is done by simply setting the
-Nst to Nb.
-
-
-Layout of the .git directory
-----------------------------
-
-  HEAD			-> refs/heads/<something>
-  objects/
-    ??/
-    ...
-  refs/
-    heads/
-      master		- the master commit id
-      ...
-    tags/
-      ...
-    branches/
-      ...
-    patches/
-      master/
-        applied		- list of applied patches
-        unapplied		- list of not-yet applied patches
-        current		- name of the topmost patch
-        patch1/
-          bottom		- the bottom id of the patch
-          top		- the top id of the patch
-  	description	- the patch description
-  	authname	- author's name
-  	authemail	- author's e-mail
-  	commname	- committer's name
-  	commemail	- committer's e-mail
-        patch2/
-          ...
-        ...
-      ...
+TODO:: This section needs revising. I've only fixed the formatting.
+
+stglink:export[] and stglink: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
+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.

Re: [StGit PATCH 2/6] Remove TODO items that have already been addressed

[Catalin Marinas]

2008/10/5 Karl Hasselström <kha@treskal.com>:
>  TODO |    9 ---------
>  1 files changed, 0 insertions(+), 9 deletions(-)

We could also drop this file entirely since we have a Tasks list on
the gna.org project page.

-- 
Catalin

Re: [StGit PATCH 4/6] Add 1.0 TODO items from recent discussion by private mail

[Catalin Marinas]

2008/10/5 Karl Hasselström <kha@treskal.com>:
> +- Convert the remaining commands to the new infrastructure.
> +
> +- Go through the design of the UI and make sure there's nothing hard
> +  to change in there that we'll regret later.
> +
> +- Write a user guide. I'm thinking a document on the order of 10-30
> +  pages that'll explain why one would want to use StGit, and how.
> +
> +- Make sure the rest of the documentation is in good shape.

Actually, at least for these kind of things we should still keep this
file. We could drop it after 1.0.

-- 
Catalin

Re: [StGit PATCH 5/6] Refresh the main stg man page

[Catalin Marinas]

2008/10/5 Karl Hasselström <kha@treskal.com>:
> Update the text to reflect what's happened in StGit in the last few
> releases. Also, consistently capitalize the names "Git" and "StGit".

I need to change the websites as well (BTW, I gave you admin rights on
the gna.org project page).

> --- a/Documentation/stg.txt
> +++ b/Documentation/stg.txt
[...]
> +  * After making changes to the worktree, you can incorporate the
> +    changes into an existing patch; this is called 'refreshing'. You
> +    may refresh any patch, not just the topmost one.

I wouldn't advertise the refreshing of "any" patch as it doesn't
always work (it actually fails in a lot of cases). Or at least we
could mention that there are some restrictions.

> +  * You can easily 'rebase' your patch stack on top of any other Git
> +    branch.

It might be better with something like "on top of a different Git
commit". The first thought when reading the above is that you can move
the patch stack to a different Git branch easily, which is not the
case (you need to cherry-pick the patches).

> +  * The patch stack is just some extra metadata attached to regular
> +    Git commits, so you can continue to use Git tools along with
> +    StGit.

Again, this is with some restrictions (or there aren't any with the
new infrastructure?).

> +  Tracking changes from a remote branch, while maintaining local
> +  modifications against that branch, possibly with the intent of
> +  sending some patches upstream. You can modify your patch stack as
> +  much as you want, and when your patches are finally accepted
> +  upstream, the permanent recorded Git history will contain just the
> +  final sequence of patches, and not the messy sequence of edits that
> +  produced them.

Maybe we could mention that the local history is also clean, not only
the upstream tree (though you mention it later in a different hunk).

-- 
Catalin

Re: [StGit PATCH 5/6] Refresh the main stg man page

[Catalin Marinas]

2008/10/5 Karl Hasselström <kha@treskal.com>:
> +  * You can easily 'rebase' your patch stack on top of any other Git
> +    branch. (The 'base' of a patch stack is the most recent Git commit
> +    that is not an StGit patch.) For example, if you started making

You may want to move the bracket before the dot.

-- 
Catalin

Re: [StGit PATCH 6/6] Refresh and expand the tutorial (not finished)

[Catalin Marinas]

2008/10/5 Karl Hasselström <kha@treskal.com>:
> This is a first pass at expanding the tutorial, fixing its formatting,
> and updating it with the new things that have happened in StGit.
>
> There are a number of things still left to do in the second half of
> the document; they are tagged with "TODO".

Thanks for this. Even with the TODOs, I think we can merge them into
the master branch so that I have the same copy as you. Do you plan to
do more work on the tutorial (so that we don't duplicate)?

> -Layout of the .git directory

Should we mention the metadata storage somewhere? This is probably too
advanced for the tutorial but might be useful to have it in a
development document (for other to understand where we keep things).
Actually, is the automatically generated documentation from the new
infrastructure enough?

-- 
Catalin

Re: [StGit PATCH 5/6] Refresh the main stg man page

[Samuel Tardieu]

>>>>> "Catalin" == Catalin Marinas <catalin.marinas@gmail.com> writes:

Catalin> I wouldn't advertise the refreshing of "any" patch as it
Catalin> doesn't always work (it actually fails in a lot of cases). Or
Catalin> at least we could mention that there are some restrictions.

Does it? I use it all the times.

  Sam
-- 
Samuel Tardieu -- sam@rfc1149.net -- http://www.rfc1149.net/

Re: [StGit PATCH 2/6] Remove TODO items that have already been addressed

[Karl Hasselström]

On 2008-10-06 21:43:47 +0100, Catalin Marinas wrote:

> 2008/10/5 Karl Hasselström <kha@treskal.com>:
>
> >  TODO |    9 ---------
> >  1 files changed, 0 insertions(+), 9 deletions(-)
>
> We could also drop this file entirely since we have a Tasks list on
> the gna.org project page.

Right, that's probably a good idea.

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle

Re: [StGit PATCH 4/6] Add 1.0 TODO items from recent discussion by private mail

[Karl Hasselström]

On 2008-10-06 21:50:32 +0100, Catalin Marinas wrote:

> 2008/10/5 Karl Hasselström <kha@treskal.com>:
>
> > +- Convert the remaining commands to the new infrastructure.
> > +
> > +- Go through the design of the UI and make sure there's nothing hard
> > +  to change in there that we'll regret later.
> > +
> > +- Write a user guide. I'm thinking a document on the order of 10-30
> > +  pages that'll explain why one would want to use StGit, and how.
> > +
> > +- Make sure the rest of the documentation is in good shape.
>
> Actually, at least for these kind of things we should still keep
> this file. We could drop it after 1.0.

Hmm, OK. Though the issue tracker would probably handle this kind of
stuff too -- doesn't it have a way to tag issues with the desired
milestone, and then present a view with, for example, all the
remaining "1.0" issues?

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle

Re: [StGit PATCH 6/6] Refresh and expand the tutorial (not finished)

[Karl Hasselström]

On 2008-10-06 22:25:45 +0100, Catalin Marinas wrote:

> 2008/10/5 Karl Hasselström <kha@treskal.com>:
>
> > This is a first pass at expanding the tutorial, fixing its
> > formatting, and updating it with the new things that have happened
> > in StGit.
> >
> > There are a number of things still left to do in the second half
> > of the document; they are tagged with "TODO".
>
> Thanks for this. Even with the TODOs, I think we can merge them into
> the master branch so that I have the same copy as you.

OK, that makes sense; "master" is, after all, a development branch. A
stable development branch, but still a development branch.

> Do you plan to do more work on the tutorial (so that we don't
> duplicate)?

I was planning to finish it if nobody else stepped up. But it'd be
great if I didn't have to do it alone. :-)

I guess we can avoid duplicate work if we send out a mail saying "I'll
now be working on part XXX" before we start writing.

> > -Layout of the .git directory
>
> Should we mention the metadata storage somewhere? This is probably
> too advanced for the tutorial but might be useful to have it in a
> development document (for other to understand where we keep things).

Yes, probably.

> Actually, is the automatically generated documentation from the new
> infrastructure enough?

I doubt it. It probably could be made enough, though, but I don't know
if that'd be better or worse than a separate document -- the code
documentation is tightly tied to the code, and I'm not sure if we want
that in this case.

We can let whoever writes it decide.

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle

Re: [StGit PATCH 5/6] Refresh the main stg man page

[Karl Hasselström]

On 2008-10-06 22:15:42 +0100, Catalin Marinas wrote:

> 2008/10/5 Karl Hasselström <kha@treskal.com>:
>
> > +  * You can easily 'rebase' your patch stack on top of any other Git
> > +    branch. (The 'base' of a patch stack is the most recent Git commit
> > +    that is not an StGit patch.) For example, if you started making
>
> You may want to move the bracket before the dot.

You mean like this?

  You can easily 'rebase' your patch stack on top of any other Git
  branch (the 'base' of a patch stack is the most recent Git commit
  that is not an StGit patch).

I slightly prefer the original, since the paretheses contain a full
stand-alone sentence, but it doesn't matter that much.

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle

Re: [StGit PATCH 5/6] Refresh the main stg man page

[Karl Hasselström]

On 2008-10-06 22:14:05 +0100, Catalin Marinas wrote:

> 2008/10/5 Karl Hasselström <kha@treskal.com>:
>
> > --- a/Documentation/stg.txt
> > +++ b/Documentation/stg.txt
> [...]
> > +  * After making changes to the worktree, you can incorporate the
> > +    changes into an existing patch; this is called 'refreshing'. You
> > +    may refresh any patch, not just the topmost one.
>
> I wouldn't advertise the refreshing of "any" patch as it doesn't
> always work (it actually fails in a lot of cases). Or at least we
> could mention that there are some restrictions.

Well, when it does fail, it fails in a controlled way, and lets the
user manually sort out the conflicts or undo. But I guess we could say
that.

When I wrote this, I didn't yet have a "Conflicts" chapter to point
to. :-)

> > +  * You can easily 'rebase' your patch stack on top of any other Git
> > +    branch.
>
> It might be better with something like "on top of a different Git
> commit". The first thought when reading the above is that you can
> move the patch stack to a different Git branch easily, which is not
> the case (you need to cherry-pick the patches).

Right, that makes sense. (We might want to mention "remote branch"
explicitly, though, since that's by far the most common case.)

> > +  * The patch stack is just some extra metadata attached to regular
> > +    Git commits, so you can continue to use Git tools along with
> > +    StGit.
>
> Again, this is with some restrictions (or there aren't any with the
> new infrastructure?).

Well, "stg undo" can repair any havoc the git tools can make. And by
"havoc" I mean merge or rebase.

This should probably grow a short disclaimer, and point to the "git
interoperability" chapter.

> > +  Tracking changes from a remote branch, while maintaining local
> > +  modifications against that branch, possibly with the intent of
> > +  sending some patches upstream. You can modify your patch stack as
> > +  much as you want, and when your patches are finally accepted
> > +  upstream, the permanent recorded Git history will contain just the
> > +  final sequence of patches, and not the messy sequence of edits that
> > +  produced them.
>
> Maybe we could mention that the local history is also clean, not
> only the upstream tree (though you mention it later in a different
> hunk).

Hmm, yes. Though I can't immediately think of any wording that doesn't
make that paragraph a lot more complicated. Suggestions welcome.

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle

Re: [StGit PATCH 6/6] Refresh and expand the tutorial (not finished)

[Karl Hasselström]

On 2008-10-07 09:12:23 +0200, Karl Hasselström wrote:

> On 2008-10-06 22:25:45 +0100, Catalin Marinas wrote:
>
> > Do you plan to do more work on the tutorial (so that we don't
> > duplicate)?
>
> I was planning to finish it if nobody else stepped up. But it'd be
> great if I didn't have to do it alone. :-)
>
> I guess we can avoid duplicate work if we send out a mail saying
> "I'll now be working on part XXX" before we start writing.

This means that the tutorial patch needs to be pretty much immutable,
so you can merge it right away. I'll address your comments in
follow-up patches.

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle