Don't special-case the "master" branch during branch delete

[stgit] / Documentation / stg.txt

diff --git a/Documentation/stg.txt b/Documentation/stg.txt
index 002606f..4f9d18e 100644 (file)
--- a/Documentation/stg.txt
+++ b/Documentation/stg.txt
@@ -1,4 +1,4 @@
-stg(7)
+stg(1)

 ======
 Yann Dirson <ydirson@altern.org>
 v0.12.1, February 2007
 ======
 Yann Dirson <ydirson@altern.org>
 v0.12.1, February 2007


@@ -10,7 +10,9 @@ stg - manage stacks of patches using the GIT content tracker
 SYNOPSIS
 --------
 [verse]
 SYNOPSIS
 --------
 [verse]

-'stg' [--version] [--help] <command> [OPTIONS] [ARGS]
+'stg' [--version | --help]
+'stg' [--help <command> | <command> --help]
+'stg' <command> [COMMAND OPTIONS] [ARGS]

 
 DESCRIPTION
 -----------
 
 DESCRIPTION
 -----------


@@ -21,23 +23,66 @@ 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.
 
 are stored as GIT commit objects, allowing easy merging of the StGIT
 patches into other repositories using standard GIT functionality.
 

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

 Typical uses of StGIT include:
 
 Tracking branch::
 Typical uses of StGIT include:
 
 Tracking branch::

-       Maintaining modifications against a remote 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.  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.
++
+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.

 
 Development branch::
        Preparing and testing your commits before publishing them,
        separating your features from unrelated bugfixes collected
        while developping.
 
 Development branch::
        Preparing and testing your commits before publishing them,
        separating your features from unrelated bugfixes collected
        while developping.

++
+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.
+
+Patches
+~~~~~~~
+
+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').
+
+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').
+
+If you need to pass a given StGIT reference to a git command,
+stglink:id[] will convert it to a git commit id.

 
 OPTIONS
 -------
 
 
 OPTIONS
 -------
 

+The following generic option flags are available.  Additional options
+are available per-command, and documented in the command-specific
+documentation.
+

 --version::
        Prints the StGIT suite version that the 'stg' program came
        from, as well as version of other components used, such as GIT
 --version::
        Prints the StGIT suite version that the 'stg' program came
        from, as well as version of other components used, such as GIT


@@ -65,11 +110,11 @@ Generic commands
 
 User-support commands not touching the repository.
 
 
 User-support commands not touching the repository.
 

-stglink:help[]::
+stg help::

        stgdesc:help[]
        stgdesc:help[]

-stglink:version[]::
+stg version::

        stgdesc:version[]
        stgdesc:version[]

-stglink:copyright[]::
+stg copyright::

        stgdesc:copyright[]
 
 Repository commands
        stgdesc:copyright[]
 
 Repository commands


@@ -117,6 +162,8 @@ stglink:goto[]::
        stgdesc:goto[]
 stglink:float[]::
        stgdesc:float[]
        stgdesc:goto[]
 stglink:float[]::
        stgdesc:float[]

+stglink:sink[]::
+       stgdesc:sink[]

 stglink:applied[]::
        stgdesc:applied[]
 stglink:unapplied[]::
 stglink:applied[]::
        stgdesc:applied[]
 stglink:unapplied[]::