Re: [PATCH 6/6] doc: add stash export and import to docs
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Mar 16, 2022, 17:34 UTC
- Message-ID
- <xmqq35jhn6ni.fsf@gitster.g>
- In-Reply-To
- <20220310173236.4165310-7-sandals@crustytoothpaste.net>
"brian m. carlson" <sandals@crustytoothpaste.net> writes:
Show 18 quoted lines
> 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>...]
Show 5 quoted lines
> +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.
Show 5 quoted lines
> +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.
Show 23 quoted lines
> 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}`).