From 26aab5b04fa4ba13f48948de73e497cf0a315ad1 Mon Sep 17 00:00:00 2001 From: Catalin Marinas Date: Sun, 24 Jul 2005 11:44:10 +0100 Subject: [PATCH] Improve the help message for commands Signed-off-by: Catalin Marinas --- stgit/commands/add.py | 6 +++++- stgit/commands/applied.py | 6 +++++- stgit/commands/clean.py | 6 +++++- stgit/commands/delete.py | 7 ++++++- stgit/commands/diff.py | 13 ++++++++++++- stgit/commands/export.py | 19 +++++++++++++++++-- stgit/commands/files.py | 8 +++++++- stgit/commands/init.py | 9 ++++++++- stgit/commands/mail.py | 40 +++++++++++++++++++++++++++++++++++++++- stgit/commands/new.py | 9 ++++++++- stgit/commands/pop.py | 6 +++++- stgit/commands/pull.py | 14 +++++++++++++- stgit/commands/push.py | 13 ++++++++++++- stgit/commands/refresh.py | 10 +++++++++- stgit/commands/resolved.py | 6 +++++- stgit/commands/rm.py | 5 ++++- stgit/commands/series.py | 6 +++++- stgit/commands/status.py | 15 ++++++++++++++- stgit/commands/top.py | 4 +++- stgit/commands/unapplied.py | 5 ++++- 20 files changed, 186 insertions(+), 21 deletions(-) diff --git a/stgit/commands/add.py b/stgit/commands/add.py index 7bad07c..999ce2b 100644 --- a/stgit/commands/add.py +++ b/stgit/commands/add.py @@ -25,7 +25,11 @@ from stgit import stack, git help = 'add files or directories to the repository' -usage = """%prog """ +usage = """%prog [options] + +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 = [] diff --git a/stgit/commands/applied.py b/stgit/commands/applied.py index 94b26c6..8a2a232 100644 --- a/stgit/commands/applied.py +++ b/stgit/commands/applied.py @@ -25,7 +25,11 @@ from stgit import stack, git 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 = [] diff --git a/stgit/commands/clean.py b/stgit/commands/clean.py index efd85c2..3c2649b 100644 --- a/stgit/commands/clean.py +++ b/stgit/commands/clean.py @@ -24,7 +24,11 @@ from stgit import stack, git 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', diff --git a/stgit/commands/delete.py b/stgit/commands/delete.py index a003082..01bea62 100644 --- a/stgit/commands/delete.py +++ b/stgit/commands/delete.py @@ -25,7 +25,12 @@ from stgit import stack, git help = 'remove the topmost or any unapplied patch' -usage = '%prog ' +usage = """%prog [options] + +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 = [] diff --git a/stgit/commands/diff.py b/stgit/commands/diff.py index b6ed82e..6a730ee 100644 --- a/stgit/commands/diff.py +++ b/stgit/commands/diff.py @@ -27,7 +27,18 @@ from stgit import stack, git help = 'show the tree diff' usage = """%prog [options] [] -The revision format is '([patch]/[bottom | top]) | '""" +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]) | | 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'), diff --git a/stgit/commands/export.py b/stgit/commands/export.py index db7b560..40f1a48 100644 --- a/stgit/commands/export.py +++ b/stgit/commands/export.py @@ -27,10 +27,25 @@ from stgit import stack, git help = 'exports a series of patches to (or patches)' -usage = """%prog [options] []""" +usage = """%prog [options] [] + +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', diff --git a/stgit/commands/files.py b/stgit/commands/files.py index 35be5db..9ce926f 100644 --- a/stgit/commands/files.py +++ b/stgit/commands/files.py @@ -25,7 +25,13 @@ from stgit import stack, git help = 'show the files modified by a patch (or the current patch)' -usage = '%prog [options] []' +usage = """%prog [options] [] + +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', diff --git a/stgit/commands/init.py b/stgit/commands/init.py index 77ee1a2..0326f9a 100644 --- a/stgit/commands/init.py +++ b/stgit/commands/init.py @@ -25,7 +25,14 @@ from stgit import stack, git 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 = [] diff --git a/stgit/commands/mail.py b/stgit/commands/mail.py index ceccdd6..0b3159b 100644 --- a/stgit/commands/mail.py +++ b/stgit/commands/mail.py @@ -26,7 +26,45 @@ from stgit.config import config help = 'send a patch or series of patches by e-mail' -usage = """%prog [options] []""" +usage = """%prog [options] [] + +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', diff --git a/stgit/commands/new.py b/stgit/commands/new.py index c36e109..9efecc1 100644 --- a/stgit/commands/new.py +++ b/stgit/commands/new.py @@ -25,7 +25,14 @@ from stgit import stack, git help = 'create a new patch and make it the topmost one' -usage = '%prog [options] ' +usage = """%prog [options] + +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'), diff --git a/stgit/commands/pop.py b/stgit/commands/pop.py index fb85eb8..3da135c 100644 --- a/stgit/commands/pop.py +++ b/stgit/commands/pop.py @@ -25,7 +25,11 @@ from stgit import stack, git 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', diff --git a/stgit/commands/pull.py b/stgit/commands/pull.py index 1e37cb2..ab7466e 100644 --- a/stgit/commands/pull.py +++ b/stgit/commands/pull.py @@ -24,7 +24,19 @@ from stgit import stack, git 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/ 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', diff --git a/stgit/commands/push.py b/stgit/commands/push.py index 65462b3..6325483 100644 --- a/stgit/commands/push.py +++ b/stgit/commands/push.py @@ -25,7 +25,18 @@ from stgit import stack, git help = 'push a patch on top of the series' -usage = '%prog [options] []' +usage = """%prog [options] [] + +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', diff --git a/stgit/commands/refresh.py b/stgit/commands/refresh.py index 46a7ea2..f5cb2e9 100644 --- a/stgit/commands/refresh.py +++ b/stgit/commands/refresh.py @@ -26,7 +26,15 @@ from stgit.config import config 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 '\ diff --git a/stgit/commands/resolved.py b/stgit/commands/resolved.py index c9ae6ca..d98ca9a 100644 --- a/stgit/commands/resolved.py +++ b/stgit/commands/resolved.py @@ -25,7 +25,11 @@ from stgit import stack, git help = 'mark a file conflict as solved' -usage = '%prog [options] [[ ]]' +usage = """%prog [options] [] + +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 .{local,remote,older} files.""" options = [make_option('-a', '--all', help = 'mark all conflicts as solved', diff --git a/stgit/commands/rm.py b/stgit/commands/rm.py index 9d06e9a..2005005 100644 --- a/stgit/commands/rm.py +++ b/stgit/commands/rm.py @@ -25,7 +25,10 @@ from stgit import stack, git help = 'remove files from the repository' -usage = '%prog [options] ' +usage = """%prog [options] + +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', diff --git a/stgit/commands/series.py b/stgit/commands/series.py index 8559d25..fb8abb7 100644 --- a/stgit/commands/series.py +++ b/stgit/commands/series.py @@ -25,7 +25,11 @@ from stgit import stack, git 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 = [] diff --git a/stgit/commands/status.py b/stgit/commands/status.py index 65bffac..15fbcf3 100644 --- a/stgit/commands/status.py +++ b/stgit/commands/status.py @@ -25,7 +25,20 @@ from stgit import stack, git help = 'show the tree status' -usage = '%prog [options] []' +usage = """%prog [options] [] + +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', diff --git a/stgit/commands/top.py b/stgit/commands/top.py index 676c7ad..1d6ab5e 100644 --- a/stgit/commands/top.py +++ b/stgit/commands/top.py @@ -25,7 +25,9 @@ from stgit import stack, git help = 'print the name of the top patch' -usage = '%prog' +usage = """%prog [options] + +Print the name of the current (topmost) patch.""" options = [] diff --git a/stgit/commands/unapplied.py b/stgit/commands/unapplied.py index 5d7564a..fe6a485 100644 --- a/stgit/commands/unapplied.py +++ b/stgit/commands/unapplied.py @@ -25,7 +25,10 @@ from stgit import stack, git 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 = [] -- 2.11.0