doc: stash: split options from description (2)
Together with the previous patch, this brings docs for `git stash` to the common layout used for most other commands (see for example docs for `git add`, `git commit`, `git checkout`, `git reset`) where all options are documented in a separate list. After some thinking and having a look at docs for `git svn` and `git `submodule`, I have arrived at following conclusions: * Options should be described in a list rather then text to facilitate lookup for user. * Single list is better then multiple lists because it avoids copy&pasting descriptions between subcommands (or, without copy&pasting, user will have to look up missing options in other subcommands). * As a consequence, commands section should only give brief info and list possible options. Since options have good enough names, user will only need to look up the "interesting" options. * Every option should list which subcommands support it. I have decided to use alphabetical sorting in the list of options to facilitate lookup for user. There is some text editing done to make old descriptions better fit into the list-style format. Signed-off-by: Alexandr Miloslavskiy <alexandr.miloslavskiy@syntevo.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Alexandr Miloslavskiy committed
Feb 17, 2020 at 17:25 UTC
0093abc286fe3f195f702de28c6d9af009dda8e0
1 file changed
+57
-35
Documentation/git-stash.txt
+57
-35
@@ -43,8 +43,8 @@ created stash, `stash@{1}` is the one before it, `stash@{2.hours.ago}`
43
is also possible). Stashes may also be referenced by specifying just the
44
stash index (e.g. the integer `n` is equivalent to `stash@{n}`).
45
46
-OPTIONS
47
--------
46
+COMMANDS
47
+--------
48
49
push [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--] [<pathspec>...]::
50
@@ -86,7 +86,7 @@ show [<options>] [<stash>]::
86
87
Show the changes recorded in the stash entry as a diff between the
88
stashed contents and the commit back when the stash entry was first
89
- created. When no `<stash>` is given, it shows the latest one.
89
+ created.
90
By default, the command shows the diffstat, but it will accept any
91
format known to 'git diff' (e.g., `git stash show -p stash@{1}`
92
to view the second most recent entry in patch form).
@@ -116,8 +116,7 @@ branch <branchname> [<stash>]::
116
the commit at which the `<stash>` was originally created, applies the
117
changes recorded in `<stash>` to the new working tree and index.
118
If that succeeds, and `<stash>` is a reference of the form
119
- `stash@{<revision>}`, it then drops the `<stash>`. When no `<stash>`
120
- is given, applies the latest one.
119
+ `stash@{<revision>}`, it then drops the `<stash>`.
120
+
121
This is useful if the branch on which you ran `git stash push` has
122
changed enough that `git stash apply` fails due to conflicts. Since
@@ -133,9 +132,6 @@ clear::
132
drop [-q|--quiet] [<stash>]::
133
134
Remove a single stash entry from the list of stash entries.
136
- When no `<stash>` is given, it removes the latest one.
137
- i.e. `stash@{0}`, otherwise `<stash>` must be a valid stash
138
- log reference of the form `stash@{<revision>}`.
135
136
create::
137
@@ -152,40 +148,66 @@ store::
148
reflog. This is intended to be useful for scripts. It is
149
probably not the command you want to use; see "push" above.
150
155
-If the `--all` option is used instead then the
156
-ignored files are stashed and cleaned in addition to the untracked files.
157
-
158
-If the `--include-untracked` option is used, all untracked files are also
159
-stashed and then cleaned up with `git clean`, leaving the working directory
160
-in a very clean state.
151
+OPTIONS
152
+-------
153
+-a::
154
+--all::
155
+ This option is only valid for `push` and `save` commands.
156
++
157
+All ignored and untracked files are also stashed and then cleaned
158
+up with `git clean`.
159
162
-If the `--index` option is used, then tries to reinstate not only the working
163
-tree's changes, but also the index's ones. However, this can fail, when you
164
-have conflicts (which are stored in the index, where you therefore can no
165
-longer apply the changes as they were originally).
160
+-u::
161
+--include-untracked::
162
+ This option is only valid for `push` and `save` commands.
163
++
164
+All untracked files are also stashed and then cleaned up with
165
+`git clean`.
166
167
-If the `--keep-index` option is used, all changes already added to the
168
-index are left intact.
167
+--index::
168
+ This option is only valid for `pop` and `apply` commands.
169
++
170
+Tries to reinstate not only the working tree's changes, but also
171
+the index's ones. However, this can fail, when you have conflicts
172
+(which are stored in the index, where you therefore can no longer
173
+apply the changes as they were originally).
174
+
175
+-k::
176
+--keep-index::
177
+--no-keep-index::
178
+ This option is only valid for `push` and `save` commands.
179
++
180
+All changes already added to the index are left intact.
181
170
-With `--patch`, you can interactively select hunks from the diff
171
-between HEAD and the working tree to be stashed. The stash entry is
172
-constructed such that its index state is the same as the index state
173
-of your repository, and its worktree contains only the changes you
174
-selected interactively. The selected changes are then rolled back
175
-from your worktree. See the ``Interactive Mode'' section of
176
-linkgit:git-add[1] to learn how to operate the `--patch` mode.
182
+-p::
183
+--patch::
184
+ This option is only valid for `push` and `save` commands.
185
++
186
+Interactively select hunks from the diff between HEAD and the
187
+working tree to be stashed. The stash entry is constructed such
188
+that its index state is the same as the index state of your
189
+repository, and its worktree contains only the changes you selected
190
+interactively. The selected changes are then rolled back from your
191
+worktree. See the ``Interactive Mode'' section of linkgit:git-add[1]
192
+to learn how to operate the `--patch` mode.
193
+
194
The `--patch` option implies `--keep-index`. You can use
195
`--no-keep-index` to override this.
196
181
-When pathspec is given to 'git stash push', the new stash entry records the
182
-modified states only for the files that match the pathspec. The index
183
-entries and working tree files are then rolled back to the state in
184
-HEAD only for these files, too, leaving files that do not match the
185
-pathspec intact.
186
-
187
-When no `<stash>` is given, `stash@{0}` is assumed, otherwise `<stash>` must
188
-be a reference of the form `stash@{<revision>}`.
197
+<pathspec>...::
198
+ This option is only valid for `push` command.
199
++
200
+The new stash entry records the modified states only for the files
201
+that match the pathspec. The index entries and working tree files
202
+are then rolled back to the state in HEAD only for these files,
203
+too, leaving files that do not match the pathspec intact.
204
+
205
+<stash>::
206
+ This option is only valid for `apply`, `branch`, `drop`, `pop`,
207
+ `show` commands.
208
++
209
+A reference of the form `stash@{<revision>}`. When no `<stash>` is
210
+given, the latest stash is assumed (that is, `stash@{0}`).
211
212
DISCUSSION
213
----------