freshlybakedca.ke
Git fork
doc: convert git-stash.adoc to synopis style
- Switch the synopsis to a synopsis block which will automatically
format placeholders in italics and keywords in monospace
- Use _<placeholder>_ instead of <placeholder> in the description
- Use `backticks` for keywords and more complex option
descriptions. The new rendering engine will apply synopsis rules to
these spans.
Also do not refer to the man page in the description of settings when this
description is already in the man page.
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
authored by
Jean-Noël Avila
and committed by
Junio C Hamano
a92d0607
45547b60
+19
-10
Documentation/config/stash.adoc
+19
-10
Documentation/config/stash.adoc
···
1
-
stash.index::
1
+
ifndef::git-stash[]
2
+
:see-show: See the description of the 'show' command in linkgit:git-stash[1].
3
+
endif::git-stash[]
4
+
5
+
ifdef::git-stash[]
6
+
:see-show:
7
+
endif::git-stash[]
8
+
9
+
`stash.index`::
2
10
If this is set to true, `git stash apply` and `git stash pop` will
3
-
behave as if `--index` was supplied. Defaults to false. See the
4
-
descriptions in linkgit:git-stash[1].
11
+
behave as if `--index` was supplied. Defaults to false.
12
+
ifndef::git-stash[]
13
+
See the descriptions in linkgit:git-stash[1].
14
+
endif::git-stash[]
5
15
6
-
stash.showIncludeUntracked::
16
+
`stash.showIncludeUntracked`::
7
17
If this is set to true, the `git stash show` command will show
8
-
the untracked files of a stash entry. Defaults to false. See
9
-
the description of the 'show' command in linkgit:git-stash[1].
18
+
the untracked files of a stash entry. Defaults to false. {see-show}
10
19
11
-
stash.showPatch::
20
+
`stash.showPatch`::
12
21
If this is set to true, the `git stash show` command without an
13
22
option will show the stash entry in patch form. Defaults to false.
14
-
See the description of the 'show' command in linkgit:git-stash[1].
23
+
{see-show}
15
24
16
-
stash.showStat::
25
+
`stash.showStat`::
17
26
If this is set to true, the `git stash show` command without an
18
27
option will show a diffstat of the stash entry. Defaults to true.
19
-
See the description of the 'show' command in linkgit:git-stash[1].
28
+
{see-show}
+66
-68
Documentation/git-stash.adoc
+66
-68
Documentation/git-stash.adoc
···
7
7
8
8
SYNOPSIS
9
9
--------
10
-
[verse]
11
-
'git stash' list [<log-options>]
12
-
'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]
13
-
'git stash' drop [-q | --quiet] [<stash>]
14
-
'git stash' pop [--index] [-q | --quiet] [<stash>]
15
-
'git stash' apply [--index] [-q | --quiet] [<stash>]
16
-
'git stash' branch <branchname> [<stash>]
17
-
'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
10
+
[synopsis]
11
+
git stash list [<log-options>]
12
+
git stash show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]
13
+
git stash drop [-q | --quiet] [<stash>]
14
+
git stash pop [--index] [-q | --quiet] [<stash>]
15
+
git stash apply [--index] [-q | --quiet] [<stash>]
16
+
git stash branch <branchname> [<stash>]
17
+
git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
18
18
[-u | --include-untracked] [-a | --all] [(-m | --message) <message>]
19
19
[--pathspec-from-file=<file> [--pathspec-file-nul]]
20
20
[--] [<pathspec>...]]
21
-
'git stash' save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
22
-
[-u | --include-untracked] [-a | --all] [<message>]
23
-
'git stash' clear
24
-
'git stash' create [<message>]
25
-
'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>
26
-
'git stash' export (--print | --to-ref <ref>) [<stash>...]
27
-
'git stash' import <commit>
21
+
git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
22
+
[-u | --include-untracked] [-a | --all] [<message>]
23
+
git stash clear
24
+
git stash create [<message>]
25
+
git stash store [(-m | --message) <message>] [-q | --quiet] <commit>
26
+
git stash export (--print | --to-ref <ref>) [<stash>...]
27
+
git stash import <commit>
28
28
29
29
DESCRIPTION
30
30
-----------
···
38
38
`git stash list`, inspected with `git stash show`, and restored
39
39
(potentially on top of a different commit) with `git stash apply`.
40
40
Calling `git stash` without any arguments is equivalent to `git stash push`.
41
-
A stash is by default listed as "WIP on 'branchname' ...", but
41
+
A stash is by default listed as "WIP on '<branchname>' ...", but
42
42
you can give a more descriptive message on the command line when
43
43
you create one.
44
44
···
47
47
the usual reflog syntax (e.g. `stash@{0}` is the most recently
48
48
created stash, `stash@{1}` is the one before it, `stash@{2.hours.ago}`
49
49
is also possible). Stashes may also be referenced by specifying just the
50
-
stash index (e.g. the integer `n` is equivalent to `stash@{n}`).
50
+
stash index (e.g. the integer `<n>` is equivalent to `stash@{<n>}`).
51
51
52
52
COMMANDS
53
53
--------
54
54
55
-
push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [(-m|--message) <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]::
55
+
`push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-u | --include-untracked] [ -a | --all] [-q | --quiet] [(-m|--message) <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]`::
56
56
57
57
Save your local modifications to a new 'stash entry' and roll them
58
-
back to HEAD (in the working tree and in the index).
59
-
The <message> part is optional and gives
58
+
back to `HEAD` (in the working tree and in the index).
59
+
The _<message>_ part is optional and gives
60
60
the description along with the stashed state.
61
61
+
62
62
For quickly making a snapshot, you can omit "push". In this mode,
···
65
65
are `stash -p` which acts as alias for `stash push -p` and pathspec elements,
66
66
which are allowed after a double hyphen `--` for disambiguation.
67
67
68
-
save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]::
68
+
`save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-u | --include-untracked] [-a | --all] [-q | --quiet] [<message>]`::
69
69
70
70
This option is deprecated in favour of 'git stash push'. It
71
71
differs from "stash push" in that it cannot take pathspec.
72
72
Instead, all non-option arguments are concatenated to form the stash
73
73
message.
74
74
75
-
list [<log-options>]::
75
+
`list [<log-options>]`::
76
76
77
77
List the stash entries that you currently have. Each 'stash entry' is
78
78
listed with its name (e.g. `stash@{0}` is the latest entry, `stash@{1}` is
···
88
88
The command takes options applicable to the 'git log'
89
89
command to control what is shown and how. See linkgit:git-log[1].
90
90
91
-
show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]::
91
+
`show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]`::
92
92
93
93
Show the changes recorded in the stash entry as a diff between the
94
94
stashed contents and the commit back when the stash entry was first
···
96
96
By default, the command shows the diffstat, but it will accept any
97
97
format known to 'git diff' (e.g., `git stash show -p stash@{1}`
98
98
to view the second most recent entry in patch form).
99
-
If no `<diff-option>` is provided, the default behavior will be given
99
+
If no _<diff-option>_ is provided, the default behavior will be given
100
100
by the `stash.showStat`, and `stash.showPatch` config variables. You
101
101
can also use `stash.showIncludeUntracked` to set whether
102
102
`--include-untracked` is enabled by default.
103
103
104
-
pop [--index] [-q|--quiet] [<stash>]::
104
+
`pop [--index] [-q | --quiet] [<stash>]`::
105
105
106
106
Remove a single stashed state from the stash list and apply it
107
107
on top of the current working tree state, i.e., do the inverse
···
112
112
removed from the stash list. You need to resolve the conflicts by hand
113
113
and call `git stash drop` manually afterwards.
114
114
115
-
apply [--index] [-q|--quiet] [<stash>]::
115
+
`apply [--index] [-q | --quiet] [<stash>]`::
116
116
117
117
Like `pop`, but do not remove the state from the stash list. Unlike `pop`,
118
118
`<stash>` may be any commit that looks like a commit created by
119
119
`stash push` or `stash create`.
120
120
121
-
branch <branchname> [<stash>]::
121
+
`branch <branchname> [<stash>]`::
122
122
123
-
Creates and checks out a new branch named `<branchname>` starting from
124
-
the commit at which the `<stash>` was originally created, applies the
125
-
changes recorded in `<stash>` to the new working tree and index.
126
-
If that succeeds, and `<stash>` is a reference of the form
127
-
`stash@{<revision>}`, it then drops the `<stash>`.
123
+
Creates and checks out a new branch named _<branchname>_ starting from
124
+
the commit at which the _<stash>_ was originally created, applies the
125
+
changes recorded in _<stash>_ to the new working tree and index.
126
+
If that succeeds, and _<stash>_ is a reference of the form
127
+
`stash@{<revision>}`, it then drops the _<stash>_.
128
128
+
129
129
This is useful if the branch on which you ran `git stash push` has
130
130
changed enough that `git stash apply` fails due to conflicts. Since
···
132
132
time `git stash` was run, it restores the originally stashed state
133
133
with no conflicts.
134
134
135
-
clear::
135
+
`clear`::
136
136
Remove all the stash entries. Note that those entries will then
137
137
be subject to pruning, and may be impossible to recover (see
138
-
'Examples' below for a possible strategy).
138
+
'EXAMPLES' below for a possible strategy).
139
139
140
-
drop [-q|--quiet] [<stash>]::
141
-
140
+
`drop [-q | --quiet] [<stash>]`::
142
141
Remove a single stash entry from the list of stash entries.
143
142
144
-
create::
145
-
143
+
`create`::
146
144
Create a stash entry (which is a regular commit object) and
147
145
return its object name, without storing it anywhere in the ref
148
146
namespace.
149
147
This is intended to be useful for scripts. It is probably not
150
148
the command you want to use; see "push" above.
151
149
152
-
store::
150
+
`store`::
153
151
154
152
Store a given stash created via 'git stash create' (which is a
155
153
dangling merge commit) in the stash ref, updating the stash
156
154
reflog. This is intended to be useful for scripts. It is
157
155
probably not the command you want to use; see "push" above.
158
156
159
-
export ( --print | --to-ref <ref> ) [<stash>...]::
157
+
`export ( --print | --to-ref <ref> ) [<stash>...]`::
160
158
161
159
Export the specified stashes, or all of them if none are specified, to
162
160
a chain of commits which can be transferred using the normal fetch and
163
161
push mechanisms, then imported using the `import` subcommand.
164
162
165
-
import <commit>::
166
-
163
+
`import <commit>`::
167
164
Import the specified stashes from the specified commit, which must have been
168
165
created by `export`, and add them to the list of stashes. To replace the
169
166
existing stashes, use `clear` first.
170
167
171
168
OPTIONS
172
169
-------
173
-
-a::
174
-
--all::
170
+
`-a`::
171
+
`--all`::
175
172
This option is only valid for `push` and `save` commands.
176
173
+
177
174
All ignored and untracked files are also stashed and then cleaned
178
175
up with `git clean`.
179
176
180
-
-u::
181
-
--include-untracked::
182
-
--no-include-untracked::
177
+
`-u`::
178
+
`--include-untracked`::
179
+
`--no-include-untracked`::
183
180
When used with the `push` and `save` commands,
184
181
all untracked files are also stashed and then cleaned up with
185
182
`git clean`.
···
187
184
When used with the `show` command, show the untracked files in the stash
188
185
entry as part of the diff.
189
186
190
-
--only-untracked::
187
+
`--only-untracked`::
191
188
This option is only valid for the `show` command.
192
189
+
193
190
Show only the untracked files in the stash entry as part of the diff.
194
191
195
-
--index::
192
+
`--index`::
196
193
This option is only valid for `pop` and `apply` commands.
197
194
+
198
195
Tries to reinstate not only the working tree's changes, but also
···
200
197
(which are stored in the index, where you therefore can no longer
201
198
apply the changes as they were originally).
202
199
203
-
-k::
204
-
--keep-index::
205
-
--no-keep-index::
200
+
`-k`::
201
+
`--keep-index`::
202
+
`--no-keep-index`::
206
203
This option is only valid for `push` and `save` commands.
207
204
+
208
205
All changes already added to the index are left intact.
209
206
210
-
-p::
211
-
--patch::
207
+
`-p`::
208
+
`--patch`::
212
209
This option is only valid for `push` and `save` commands.
213
210
+
214
211
Interactively select hunks from the diff between HEAD and the
···
224
221
225
222
include::diff-context-options.adoc[]
226
223
227
-
-S::
228
-
--staged::
224
+
`-S`::
225
+
`--staged`::
229
226
This option is only valid for `push` and `save` commands.
230
227
+
231
228
Stash only the changes that are currently staged. This is similar to
···
234
231
+
235
232
The `--patch` option has priority over this one.
236
233
237
-
--pathspec-from-file=<file>::
234
+
`--pathspec-from-file=<file>`::
238
235
This option is only valid for `push` command.
239
236
+
240
-
Pathspec is passed in `<file>` instead of commandline args. If
241
-
`<file>` is exactly `-` then standard input is used. Pathspec
237
+
Pathspec is passed in _<file>_ instead of commandline args. If
238
+
_<file>_ is exactly `-` then standard input is used. Pathspec
242
239
elements are separated by LF or CR/LF. Pathspec elements can be
243
240
quoted as explained for the configuration variable `core.quotePath`
244
241
(see linkgit:git-config[1]). See also `--pathspec-file-nul` and
245
242
global `--literal-pathspecs`.
246
243
247
-
--pathspec-file-nul::
244
+
`--pathspec-file-nul`::
248
245
This option is only valid for `push` command.
249
246
+
250
247
Only meaningful with `--pathspec-from-file`. Pathspec elements are
251
248
separated with NUL character and all other characters are taken
252
249
literally (including newlines and quotes).
253
250
254
-
-q::
255
-
--quiet::
251
+
`-q`::
252
+
`--quiet`::
256
253
This option is only valid for `apply`, `drop`, `pop`, `push`,
257
254
`save`, `store` commands.
258
255
+
259
256
Quiet, suppress feedback messages.
260
257
261
-
--print::
258
+
`--print`::
262
259
This option is only valid for the `export` command.
263
260
+
264
261
Create the chain of commits representing the exported stashes without
265
262
storing it anywhere in the ref namespace and print the object ID to
266
263
standard output. This is designed for scripts.
267
264
268
-
--to-ref::
265
+
`--to-ref`::
269
266
This option is only valid for the `export` command.
270
267
+
271
268
Create the chain of commits representing the exported stashes and store
272
269
it to the specified ref.
273
270
274
-
\--::
271
+
`--`::
275
272
This option is only valid for `push` command.
276
273
+
277
274
Separates pathspec from options for disambiguation purposes.
278
275
279
-
<pathspec>...::
276
+
`<pathspec>...`::
280
277
This option is only valid for `push` command.
281
278
+
282
279
The new stash entry records the modified states only for the files
···
286
283
+
287
284
For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
288
285
289
-
<stash>::
286
+
_<stash>_::
290
287
This option is only valid for `apply`, `branch`, `drop`, `pop`,
291
288
`show`, and `export` commands.
292
289
+
293
-
A reference of the form `stash@{<revision>}`. When no `<stash>` is
290
+
A reference of the form `stash@{<revision>}`. When no _<stash>_ is
294
291
given, the latest stash is assumed (that is, `stash@{0}`).
295
292
296
293
DISCUSSION
···
419
416
420
417
include::includes/cmd-config-section-all.adoc[]
421
418
419
+
:git-stash: 1
422
420
include::config/stash.adoc[]
423
421
424
422