X-Git-Url: https://git.distorted.org.uk/~mdw/stgit/blobdiff_plain/4ec677417c8bfb4d30b2cd7482c5ceca9b542fc8..c2a8af1d63280cf5d00574e3e059735a61fd64c9:/Documentation/stg.txt?ds=sidebyside

diff --git a/Documentation/stg.txt b/Documentation/stg.txt
index 571e53a..4f9d18e 100644
--- 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
@@ -10,7 +10,9 @@ stg - manage stacks of patches using the GIT content tracker
 SYNOPSIS
 --------
 [verse]
-'stg' [--version] [--help] <command> [OPTIONS] [ARGS]
+'stg' [--version | --help]
+'stg' [--help <command> | <command> --help]
+'stg' <command> [COMMAND OPTIONS] [ARGS]
 
 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.
 
+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::
-	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.
++
+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
 -------
 
+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
@@ -65,11 +110,11 @@ Generic commands
 
 User-support commands not touching the repository.
 
-stglink:help[]::
+stg help::
 	stgdesc:help[]
-stglink:version[]::
+stg version::
 	stgdesc:version[]
-stglink:copyright[]::
+stg copyright::
 	stgdesc:copyright[]
 
 Repository commands
@@ -117,6 +162,8 @@ stglink:goto[]::
 	stgdesc:goto[]
 stglink:float[]::
 	stgdesc:float[]
+stglink:sink[]::
+	stgdesc:sink[]
 stglink:applied[]::
 	stgdesc:applied[]
 stglink:unapplied[]::
@@ -185,6 +232,8 @@ stglink:add[]::
 	stgdesc:add[]
 stglink:rm[]::
 	stgdesc:rm[]
+stglink:cp[]::
+	stgdesc:cp[]
 stglink:status[]::
 	stgdesc:status[]
 stglink:diff[]::