[PATCH] git-stash: improve synopsis in help and manual page

Stephan Beyer· Aug 16, 2008, 03:27 UTC · lore

"git stash -h" showed some incomplete and ugly usage information. For example, the useful "--keep-index" option for "save" or the "--index" option for "apply" were not shown. Also in the documentation synopsis they were not shown, so that there is no incentive to scroll down and even see that such options exist.

This patch improves the git-stash synopsis in the documentation by mentioning that further options to the stash commands and then copies this synopsis to the usage information string of git-stash.sh.

For the latter, the dashless git command string has to be inserted on the second and the following usage lines. The code of this is taken from git-sh-setup so that all lines will show the command string.

Note that the "create" command is not advertised at all now, because it was not mentioned in git-stash.txt.

Signed-off-by: Stephan Beyer <s-beyer@gmx.net>
---
   Hi,

   btw, should the "create" command be used directly at all?
   Then a line for this should perhaps be added.

   Regards,
     Stephan

   PS: This or something like this is meant to go into 1.6.0,
       so I hope this is not too late :-)

 Documentation/git-stash.txt |    7 ++++---
 git-stash.sh                |    8 +++++++-
 2 files changed, 11 insertions(+), 4 deletions(-)

Show changes to 2 files +11 −4

Documentation/git-stash.txt, git-stash.sh

diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 7d50d74..4dd42b4 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -8,10 +8,11 @@ git-stash - Stash the changes in a dirty working directory away
 SYNOPSIS
 --------
 [verse]
-'git stash' list
-'git stash' (show | apply | drop | pop ) [<stash>]
+'git stash' list [<options>]
+'git stash' (show | drop | pop ) [<stash>]
+'git stash' [--index] apply [<stash>]
 'git stash' branch <branchname> [<stash>]
-'git stash' [save [<message>]]
+'git stash' [--keep-index] [save [<message>]]
 'git stash' clear
 
 DESCRIPTION
diff --git a/git-stash.sh b/git-stash.sh
index 5ad2c4b..d790676 100755
--- a/git-stash.sh
+++ b/git-stash.sh
@@ -1,7 +1,13 @@
 #!/bin/sh
 # Copyright (c) 2007, Nanako Shiraishi
 
-USAGE='[  | save | list | show | apply | clear | drop | pop | create | branch ]'
+dashless=$(basename "$0" | sed -e 's/-/ /')
+USAGE="list [<options>]
+   or: $dashless (show | drop | pop ) [<stash>]
+   or: $dashless [--index] apply [<stash>]
+   or: $dashless branch <branchname> [<stash>]
+   or: $dashless [--keep-index] [save [<message>]]
+   or: $dashless clear"
 
 SUBDIRECTORY_OK=Yes
 OPTIONS_SPEC=

-- 
1.6.0.rc3.10.g5a13c.dirty

Junio C Hamano· Aug 16, 2008, 09:49 UTC · re: Stephan Beyer · lore

Re: [PATCH] git-stash: improve synopsis in help and manual page

Stephan Beyer <s-beyer@gmx.net> writes:

>    btw, should the "create" command be used directly at all?
>    Then a line for this should perhaps be added.

It's pretty much for Porcelain writer's consumption, so I do not think it is worth adding it to command line help, even though it would be nice to describe it in the documentation.

Show 7 quoted lines

> +dashless=$(basename "$0" | sed -e 's/-/ /')
> +USAGE="list [<options>]
> +   or: $dashless (show | drop | pop ) [<stash>]
> +   or: $dashless [--index] apply [<stash>]
> +   or: $dashless branch <branchname> [<stash>]
> +   or: $dashless [--keep-index] [save [<message>]]
> +   or: $dashless clear"

These --index and --keep-index are subcommand options and come after them (i.e. apply/save).

patchgit-stash: improve synopsis in help and manual page