Re: [PATCH 6/6] doc: add stash export and import to docs

[Junio C Hamano <gitster@pobox.com>]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> Now that we have an easy way for users to import and export their
> stashes, let's document this in manual page so users will know how to
> use it.
>
> Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
> ---
>  Documentation/git-stash.txt | 27 +++++++++++++++++++++++++++
>  1 file changed, 27 insertions(+)
>
> diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
> index 6e15f47525..283677314a 100644
> --- a/Documentation/git-stash.txt
> +++ b/Documentation/git-stash.txt
> @@ -20,6 +20,8 @@ SYNOPSIS
>  'git stash' clear
>  'git stash' create [<message>]
>  'git stash' store [-m|--message <message>] [-q|--quiet] <commit>
> +'git stash' export ( --print | --to-ref <ref> ) [<stashes>]

Again, "[<stash>...]", I think.  Do we want SP inside () but no SP
inside []?  That looks inconsistent.

I.e.

    'git stash' export (--print|--to-ref <ref>) [<stash>...]


> +export ( --print | --to-ref <ref> ) [<stashes>]::
> +
> +	Export the specified stashes, or all of them if none are specified, to
> +	a chain of commits which can be transferred using the normal fetch and
> +	push mechanisms, then imported using the `import` subcommand.

Ditto.

> +import <commit>::
> +
> +	Import the specified stashes from the specified commit, which must have been
> +	created by `export`, and add them to the list of stashes.  To replace the
> +	existing stashes, use `clear` first.

A tangent.

I personally prefer the style to have a blank line after the
"<dt>::" in asciidoc's way of doing description list used here, both
in these two new entries and many existing ones, by the way.

We probably should do that consistently, though.

>  OPTIONS
>  -------
>  -a::
> @@ -239,6 +253,19 @@ literally (including newlines and quotes).
>  +
>  Quiet, suppress feedback messages.
>  
> +--print::
> +	This option is only valid for `export`.
> ++
> +Create the chain of commits representing the exported stashes without
> +storing it anywhere in the ref namespace and print the object ID to
> +standard output.  This is designed for scripts.
> +
> +--to-ref::
> +	This option is only valid for `export`.
> ++
> +Create the chain of commits representing the exported stashes and store
> +it to the specified ref.
> +
>  \--::
>  	This option is only valid for `push` command.
>  +

There is one more necessary update after this, no?

diff --git i/Documentation/git-stash.txt w/Documentation/git-stash.txt
index 283677314a..acce92b5d9 100644
--- i/Documentation/git-stash.txt
+++ w/Documentation/git-stash.txt
@@ -283,7 +283,7 @@ For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
 
 <stash>::
 	This option is only valid for `apply`, `branch`, `drop`, `pop`,
-	`show` commands.
+	`show`, and `export` commands.
 +
 A reference of the form `stash@{<revision>}`. When no `<stash>` is
 given, the latest stash is assumed (that is, `stash@{0}`).