help = 'add files or directories to the repository'
-usage = """%prog <files/dirs...>"""
+usage = """%prog [options] <files/dirs...>
+
+Add a the files or directories passed as arguments to the
+repository. When a directory name is given, all the files and
+subdirectories are recursively added."""
options = []
help = 'print the applied patches'
-usage = '%prog'
+usage = """%prog [options]
+
+List the patches from the series which were already pushed onto the
+stack. They are listed in the order in which they were pushed, the
+last one being the current (topmost) patch."""
options = []
help = 'delete the empty patches in the series'
-usage = """%prog [options]"""
+usage = """%prog [options]
+
+Delete the empty patches in the whole series or only those applied or
+unapplied. A patch is considered empty if the two commit objects
+representing its boundaries refer to the same tree object."""
options = [make_option('-a', '--applied',
help = 'delete the empty applied patches',
help = 'remove the topmost or any unapplied patch'
-usage = '%prog <name>'
+usage = """%prog [options] <patch>
+
+Delete the patch passed as argument. The patch to be deleted can only
+be part of the unapplied list or be the topmost one, in the latter
+case the command also popping it from the stack. Note that the
+'delete' operation is irreversible."""
options = []
help = 'show the tree diff'
usage = """%prog [options] [<files...>]
-The revision format is '([patch]/[bottom | top]) | <tree-ish>'"""
+Show the diff (default) or diffstat between the current working copy
+or a tree-ish object and another tree-ish object. File names can also
+be given to restrict the diff output. The tree-ish object can be a
+standard git commit, tag or tree. In addition to these, the command
+also supports 'base', representing the bottom of the current stack,
+and '[patch]/[bottom | top]' for the patch boundaries (defaulting to
+the current one):
+
+rev = '([patch]/[bottom | top]) | <tree-ish> | base'
+
+If neither bottom or top are given but a '/' is present, the command
+shows the specified patch (defaulting to the current one)."""
options = [make_option('-r', metavar = 'rev1[:[rev2]]', dest = 'revs',
help = 'show the diff between revisions'),
help = 'exports a series of patches to <dir> (or patches)'
-usage = """%prog [options] [<dir>]"""
+usage = """%prog [options] [<dir>]
+
+Export the applied patches into a given directory (defaults to
+'patches') in a standard unified GNU diff format. A file (defaulting
+to '.git/patchexport.tmpl') can be used as a template for the patch
+format. The following variables are supported in the template file:
+
+ %(description)s - patch description
+ %(diffstat)s - the diff statistics
+ %(authname)s - author's name
+ %(authemail)s - author's e-mail
+ %(authdate)s - patch creation date
+ %(commname)s - committer's name
+ %(commemail)s - committer's e-mail
+
+'export' can also generate a diff for a range of patches."""
options = [make_option('-n', '--numbered',
- help = 'number the patch names',
+ help = 'prefix the patch names with order numbers',
action = 'store_true'),
make_option('-d', '--diff',
help = 'append .diff to the patch names',
help = 'show the files modified by a patch (or the current patch)'
-usage = '%prog [options] [<patch>]'
+usage = """%prog [options] [<patch>]
+
+List the files modified by the given patch (defaulting to the current
+one). Passing the '--stat' option shows the diff statistics for the
+given patch. Note that this command doesn't show the files modified in
+the working tree and not yet included in the patch by a 'refresh'
+command. Use the 'diff' or 'status' commands for these files."""
options = [make_option('-s', '--stat',
help = 'show the diff stat',
help = 'initialise the tree for use with StGIT'
-usage = '%prog'
+usage = """%prog [options]
+
+Initialise a GIT repository to be used with StGIT. Note that the
+repository must be already initialised with git-init-db and the
+.git/HEAD link must point to a valid file in refs/heads/. For people
+switching between multiple branches in the same repository, the 'init'
+command has to be run on all the individual branches intended to be
+used with StGIT."""
options = []
help = 'send a patch or series of patches by e-mail'
-usage = """%prog [options] [<patch>]"""
+usage = """%prog [options] [<patch>]
+
+Send a patch or a range of patches (defaulting to the applied patches)
+by e-mail using the 'smtpserver' configuration option. The From/To/Cc
+addresses and the e-mail format are generated from the template file
+passed as argument to '--template' (defaulting to
+.git/patchmail.tmpl). A preamble e-mail can also be sent using the
+'--first' option (no default template).
+
+All the subsequent e-mails appear as replies to the first e-mail sent
+(either the preamble or the first patch). E-mails can be seen as
+replies to a different e-mail by using the '--refid' option.
+
+SMTP authentication is also possible with '--smtp-user' and
+'--smtp-password' options, also available as configuration settings:
+'smtpuser' and 'smtppassword'.
+
+The template e-mail headers and body must be separated by
+'%(endofheaders)s' variable, which is replaced by StGIT with
+additional headers and a blank line. The patch e-mail template accepts
+the following variables:
+
+ %(patch)s - patch name
+ %(shortdescr)s - the first line of the patch description
+ %(longdescr)s - the rest of the patch description, after the first line
+ %(endofheaders)s - delimiter between e-mail headers and body
+ %(diff)s - unified diff of the patch
+ %(diffstat)s - diff statistics
+ %(date)s - current date/time
+ %(patchnr)s - patch number
+ %(totalnr)s - total number of patches to be sent
+ %(authname)s - author's name
+ %(authemail)s - author's email
+ %(authdate)s - patch creation date
+ %(commname)s - committer's name
+ %(commemail)s - committer's e-mail
+
+For the preamble e-mail template, only the %(date)s, %(endofheaders)s
+and %(totalnr)s variables are supported."""
options = [make_option('-a', '--all',
help = 'e-mail all the applied patches',
help = 'create a new patch and make it the topmost one'
-usage = '%prog [options] <name>'
+usage = """%prog [options] <name>
+
+Create a new, empty patch and make it the topmost one. If the
+'--message' option is not passed, an editor is invoked with the
+.git/patchdescr.tmpl file used a as template, together with generated
+lines. By default, if there are local changes in the working tree, the
+command fails and a 'refresh' command is needed. This behaviour can be
+overridden with the '--force' option."""
options = [make_option('-m', '--message',
help = 'use MESSAGE as the patch description'),
help = 'pop the top of the series'
-usage = '%prog [options]'
+usage = """%prog [options]
+
+Pop the topmost patch or a range of patches starting with the topmost
+one from the stack. The command fails if there are local changes or
+conflicts."""
options = [make_option('-a', '--all',
help = 'pop all the applied patches',
help = 'pull the changes from the remote repository'
-usage = '%prog [options]'
+usage = """%prog [options]
+
+Pull the latest changes from the parent repository. This command works
+by popping all the patches from the stack, pulling the changes in the
+parent repository, setting the base of the stack to the latest parent
+HEAD and pusing the patches back (unless '--nopush' is specified). The
+'push' operation can fail if there are conflicts. They need to be
+resolved and the patch pushed again. The URL of the parent repository
+is specified in the .git/branches/<head> file.
+
+Note that this command doesn't perform any merge operation for the
+base of the stack, it only performs merges with the patches being
+pushed."""
options = [make_option('-n', '--nopush',
help = 'do not push the patches back after pulling',
help = 'push a patch on top of the series'
-usage = '%prog [options] [<name>]'
+usage = """%prog [options] [<name>]
+
+Push a patch (defaulting to the first unapplied one) or range of
+patches to the stack. The 'push' operation allows patch reordering by
+commuting them with the three-way merge algorithm. If the result of
+the 'push' operation is not acceptable or if there are too many
+conflicts, the '--undo' option can be used to revert the patch and the
+tree to the state before the operation. Conflicts raised during the
+push operation have to be fixed and the 'resolved' command run.
+
+The 'push' command also notifies when the patch becomes empty after
+the merge operation (i.e. it was fully merged upstream)."""
options = [make_option('-a', '--all',
help = 'push all the unapplied patches',
help = 'generate a new commit for the current patch'
-usage = '%prog [options]'
+usage = """%prog [options]
+
+Include the latest tree changes in the current patch. This command
+generates a new GIT commit object with the patch details, the previous
+one no longer being visible. The patch attributes like author,
+committer and description can be changed with the command line
+options. The '--force' option is useful when a commit object was
+created with a different tool but the changes need to be included in
+the current patch."""
options = [make_option('-f', '--force',
help = 'force the refresh even if HEAD and '\
help = 'mark a file conflict as solved'
-usage = '%prog [options] [<file>[ <file>]]'
+usage = """%prog [options] [<files...>]
+
+Mark a merge conflict as resolved. The conflicts can be seen with the
+'status' command, the corresponding files being prefixed with a
+'C'. This command also removes any <file>.{local,remote,older} files."""
options = [make_option('-a', '--all',
help = 'mark all conflicts as solved',
help = 'remove files from the repository'
-usage = '%prog [options] <files...>'
+usage = """%prog [options] <files...>
+
+Remove given files from the repository. The command doesn't remove the
+working copy of the file."""
options = [make_option('-f', '--force',
help = 'force removing even if the file exists',
help = 'print the patch series'
-usage = '%prog'
+usage = """%prog [options]
+
+Show all the patches in the series. The applied patches are prefixed
+with a '+' and the unapplied ones with a '-'. The current patch is
+prefixed with a '>'. Empty patches are prefixed with a '0'."""
options = []
help = 'show the tree status'
-usage = '%prog [options] [<files...>]'
+usage = """%prog [options] [<files...>]
+
+Show the status of the whole working copy or the given files. The
+command also shows the files in the current directory which are not
+under revision control. The files are prefixed as follows:
+
+ M - locally modified
+ N - newly added to the repository
+ D - deleted from the repository
+ C - conflict
+ ? - unknown
+
+A 'refresh' command clears the status of the modified, new and deleted
+files."""
options = [make_option('-m', '--modified',
help = 'show modified files only',
help = 'print the name of the top patch'
-usage = '%prog'
+usage = """%prog [options]
+
+Print the name of the current (topmost) patch."""
options = []
help = 'print the unapplied patches'
-usage = '%prog'
+usage = """%prog [options]
+
+List the patches from the series which are not pushed onto the stack.
+They are listed in the reverse order in which they were popped."""
options = []
~mdw / stgit / commitdiff