Add doc for 'branch'.

Signed-off-by: Yann Dirson <ydirson@altern.org>

diff --git a/Documentation/stg-branch.txt b/Documentation/stg-branch.txt
new file mode 100644 (file)
index 0000000..53f333b
--- /dev/null
+++ b/Documentation/stg-branch.txt
@@ -0,0 +1,127 @@
+stg-branch(1)
+=============
+Yann Dirson <ydirson@altern.org>
+v0.12.1, April 2007
+
+NAME
+----
+stg-branch - stgdesc:branch[]
+
+SYNOPSIS
+--------
+stg branch
+
+stg branch <branch>
+
+stg branch --list
+
+stg branch --create <newstack> [<commit-id>]
+
+stg branch --clone [<newstack>]
+
+stg branch --rename <oldname> <newname>
+
+stg branch --protect [<branch>]
+
+stg branch --unprotect [<branch>]
+
+stg branch --delete [--force] <branch>
+
+stg branch --convert
+
+DESCRIPTION
+-----------
+
+Assorted operations on branches.
+
+no command, no argument::
+       Display the name of the current branch.
+
+no command, one argument::
+       Switch to the named <branch>.
+
+--list::
+-l::
+       Display the list of branches in the current repository,
+       suffixed by the branch description if any, and optionally
+       prefixed by the letter flags 's' if the branch is an StGIT
+       stack, and 'p' if the StGIT stack is protected.  The current
+       branch is shown with a leading ">" character.
+
+--create::
+-c::
+       Create a new StGIT stack based at the specified commit, or at
+       the current HEAD if not specified.  The repository HEAD is
+       switched to the new stack.
++
+StGIT will try to detect the branch off which the new stack is forked,
+as well as the remote repository from which that parent branch is
+taken (if any), so running stgdesc:pull[] will effectively pull new
+commits from the correct branch.  It will warn if it cannot guess the
+parent branch (eg. if you do not specify a branch name as
+<commit-id>).
+
+--clone::
+       Clone the current stack, under the name <newstack> if
+       specified, or using the current stack's name suffixed by a
+       timestamp.
++
+The description of the new stack is set to tell it is a clone of the
+current stack.  The parent information of the new stack is copied from
+the current stack.
++
+Cloning a GIT branch that is not an StGIT stack is similar to creating
+a new stack off the current branch.
+
+--rename::
+-r::
+       Rename the stack named <oldname> to <newname>.
+
+--protect::
+-p::
+       Protect the named stack or the current one, preventing
+       further StGIT operations from modifying this stack.
+
+--unprotect::
+-u::
+       Remove a "protected" flag previously set with '--protect'.
+
+--delete::
+       Delete the named <branch>.  If there are any patches left in
+       the series, StGIT will refuse to delete it, unless '--force'
+       is specified.
++
+A protected branch cannot be deleted, it must be unprotected first
+(see above).
++
+When the current branch is deleted, the repository HEAD is switched to
+the "master" branch if it exists.
++
+Branch "master" is treated specially (see bug #8732), in that only the
+StGIT metadata are removed, the GIT branch itself is not destroyed.
+
+--convert::
+       Switch current stack between old and new format.
+
+OPTIONS
+-------
+
+--force::
+       Force a delete when the series is not empty.
+
+FILES
+-----
+
+       $GIT_DIR/patches/<branch>/description
+       $GIT_DIR/patches/<branch>/protected
+
+GIT CONFIGURATION VARIABLES
+---------------------------
+
+       branch.<branchname>.remote
+       branch.<branchname>.merge
+       branch.<branchname>.stgit.parentbranch
+
+StGIT
+-----
+Part of the StGIT suite - see gitlink:stg[1].