"brian m. carlson" <sandals@xxxxxxxxxxxxxxxxxxxx> 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@xxxxxxxxxxxxxxxxxxxx>
> ---
> 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}`).
