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