From: Yann Dirson <ydirson@altern.org>
Date: Tue, 10 Apr 2007 21:47:10 +0000 (+0100)
Subject: Add doc for 'branch'.
X-Git-Tag: v0.14.3~280
X-Git-Url: https://git.distorted.org.uk/~mdw/stgit/commitdiff_plain/8f51e1453990869885aa7d61f9093268fd105e1e

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