Allow 'show' and 'id' to work on non-StGIT branches (bug #10011)

[stgit] / Documentation / stg-branch.txt

stg-branch(1)
=============
Yann Dirson <ydirson@altern.org>
v0.12.1, April 2007

NAME
----
stg-branch - stgdesc:branch[]

SYNOPSIS
--------
[verse]
'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 --description=<description> [<branch>]
'stg' branch --protect [<branch>]
'stg' branch --unprotect [<branch>]
'stg' branch --delete [--force] <branch>

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

'stg' branch [-l | --list]::
	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.

'stg' branch [-c | --create]::
	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 stglink: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>).

'stg' branch --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.

'stg' branch [-r | --rename]::
	Rename the stack named <oldname> to <newname>.

'stg' branch [-d <desc> | --description=<desc>]::
	Set the branch description.

'stg' branch [-p | --protect]::
	Protect the named stack or the current one, preventing
	further StGIT operations from modifying this stack.

'stg' branch [-u | --unprotect]::
	Remove a "protected" flag previously set with '--protect'.

'stg' branch --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.

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