[PATCH 0/4] StGIT documentation updates

[PATCH 0/4] StGIT documentation updates

[Yann Dirson]

This adds a couple of new manpages, and fixes a couple of small doc
issues.

-- 
Yann Dirson    <ydirson@altern.org> |
Debian-related: <dirson@debian.org> |   Support Debian GNU/Linux:
                                    |  Freedom, Power, Stability, Gratis
     http://ydirson.free.fr/        | Check <http://www.debian.org/>

[PATCH 1/4] Fix typo in help string.

[Yann Dirson]

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

 stgit/commands/init.py |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/stgit/commands/init.py b/stgit/commands/init.py
index df2235f..46562d0 100644
--- a/stgit/commands/init.py
+++ b/stgit/commands/init.py
@@ -28,8 +28,8 @@ help = 'initialise the current branch for use with StGIT'
 usage = """%prog [options]
 
 Initialise the current GIT branch to be used as an StGIT stack. Note
-that the you must already be in a GIT repository and .git/HEAD must
-point to a valid file in refs/heads/."""
+that you must already be in a GIT repository and .git/HEAD must point
+to a valid file in refs/heads/."""
 
 options = []
 

[PATCH 2/4] Don't use section 7 for main manpage.

[Yann Dirson]

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

 Documentation/COMMAND-TEMPLATE.txt |    2 +-
 Documentation/stg-cp.txt           |    2 +-
 Documentation/stg-new.txt          |    2 +-
 Documentation/stg.txt              |    2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/COMMAND-TEMPLATE.txt b/Documentation/COMMAND-TEMPLATE.txt
index 5d8a1a9..e49a44d 100644
--- a/Documentation/COMMAND-TEMPLATE.txt
+++ b/Documentation/COMMAND-TEMPLATE.txt
@@ -38,4 +38,4 @@ GIT CONFIGURATION VARIABLES
 
 StGIT
 -----
-Part of the StGIT suite - see gitlink:stg[7].
+Part of the StGIT suite - see gitlink:stg[1].
diff --git a/Documentation/stg-cp.txt b/Documentation/stg-cp.txt
index 723d811..d28c619 100644
--- a/Documentation/stg-cp.txt
+++ b/Documentation/stg-cp.txt
@@ -57,4 +57,4 @@ FUTURE OPTIONS
 
 StGIT
 -----
-Part of the StGIT suite - see gitlink:stg[7].
+Part of the StGIT suite - see gitlink:stg[1].
diff --git a/Documentation/stg-new.txt b/Documentation/stg-new.txt
index 698816b..5775559 100644
--- a/Documentation/stg-new.txt
+++ b/Documentation/stg-new.txt
@@ -112,4 +112,4 @@ GIT CONFIGURATION VARIABLES
 
 StGIT
 -----
-Part of the StGIT suite - see gitlink:stg[7].
+Part of the StGIT suite - see gitlink:stg[1].
diff --git a/Documentation/stg.txt b/Documentation/stg.txt
index 7d92356..47934a5 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

[PATCH 3/4] Add doc for 'clone' and 'init'.

[Yann Dirson]

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

 Documentation/stg-clone.txt |   36 ++++++++++++++++++++++++++++++++++++
 Documentation/stg-init.txt  |   33 +++++++++++++++++++++++++++++++++
 2 files changed, 69 insertions(+), 0 deletions(-)

diff --git a/Documentation/stg-clone.txt b/Documentation/stg-clone.txt
new file mode 100644
index 0000000..73c0d92
--- /dev/null
+++ b/Documentation/stg-clone.txt
@@ -0,0 +1,36 @@
+stg-clone(1)
+==========
+Yann Dirson <ydirson@altern.org>
+v0.12.1, April 2007
+
+NAME
+----
+stg-clone - stgdesc:clone[]
+
+SYNOPSIS
+--------
+stg clone [OPTIONS] <repository> <dir>
+
+DESCRIPTION
+-----------
+
+Clone a GIT <repository> into the local <dir> (using
+gitlink:git-clone[1]) and initialise the resulting "master" branch as
+a patch stack.
+
+This operation is for example suitable to start working using the
+"tracking branch" workflow (see gitlink:stg[1]).  Other means to setup
+an StGIT stack are stgdesc:init[] and the '--create' and '--clone'
+commands of stgdesc:branch[].
+
+The target directory named by <dir> will be created by this command,
+and must not exist beforehand.
+
+OPTIONS
+-------
+
+No specific options.
+
+StGIT
+-----
+Part of the StGIT suite - see gitlink:stg[1].
diff --git a/Documentation/stg-init.txt b/Documentation/stg-init.txt
new file mode 100644
index 0000000..33fd387
--- /dev/null
+++ b/Documentation/stg-init.txt
@@ -0,0 +1,33 @@
+stg-init(1)
+==========
+Yann Dirson <ydirson@altern.org>
+v0.12.1, April 2007
+
+NAME
+----
+stg-init - stgdesc:init[]
+
+SYNOPSIS
+--------
+stg init [OPTIONS]
+
+DESCRIPTION
+-----------
+
+Initialise the current GIT branch to be used as an StGIT stack.  You
+must already be in a GIT repository and .git/HEAD must point to a
+valid file in refs/heads/.
+
+This operation is for example suitable to start working using the
+"development branch" workflow (see gitlink:stg[1]).  Other means to setup
+an StGIT stack are stgdesc:clone[] and the '--create' and '--clone'
+commands of stgdesc:branch[].
+
+OPTIONS
+-------
+
+No specific options.
+
+StGIT
+-----
+Part of the StGIT suite - see gitlink:stg[1].

[PATCH 4/4] Add doc for 'branch'.

[Yann Dirson]

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

 Documentation/stg-branch.txt |  127 ++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 127 insertions(+), 0 deletions(-)

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

Re: [PATCH 2/4] Don't use section 7 for main manpage.

[Catalin Marinas]

On 07/04/07, Yann Dirson <ydirson@altern.org> wrote:
> --- a/Documentation/stg.txt
> +++ b/Documentation/stg.txt
> @@ -1,4 +1,4 @@
> -stg(7)
> +stg(1)
>  ======

In error, I added commit 5906924135f886527c1e947d100073067783eaa2 that
was reverting this hunk. My reason was to be able to install the man
pages and the Makefile was still looking for stg.7. I'll revert my
commit tonight and change the Makefile.

-- 
Catalin