@matheusbsbs / matheus-bagliano / commits / a92d060749

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>

Jean-Noël Avila committed Oct 5, 2025 at 21:11 UTC a92d060749ec683fe0321808aa949fbf41694406

2 files changed +85 -78

Documentation/config/stash.adoc

+19 -10

@@ -1,19 +1,28 @@

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`::

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[]

6 -stash.showIncludeUntracked::

16 +`stash.showIncludeUntracked`::

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}

11 -stash.showPatch::

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.

14 - See the description of the 'show' command in linkgit:git-stash[1].

23 + {see-show}

16 -stash.showStat::

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.

19 - See the description of the 'show' command in linkgit:git-stash[1].

28 + {see-show}

Documentation/git-stash.adoc

+66 -68

@@ -7,24 +7,24 @@ git-stash - Stash the changes in a dirty working directory away

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]

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>

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>

29 DESCRIPTION

30 -----------

@@ -38,7 +38,7 @@ The modifications stashed away by this command can be listed with

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

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.

@@ -47,16 +47,16 @@ stashes are found in the reflog of this reference and can be named using

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}`).

50 +stash index (e.g. the integer `<n>` is equivalent to `stash@{<n>}`).

52 COMMANDS

53 --------

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 the description along with the stashed state.

61 +

62 For quickly making a snapshot, you can omit "push". In this mode,

@@ -65,14 +65,14 @@ subcommand from making an unwanted stash entry. The two exceptions to this

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.

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.

75 -list [<log-options>]::

75 +`list [<log-options>]`::

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,7 +88,7 @@ stash@{1}: On master: 9cc0589... Add git-stash

88 The command takes options applicable to the 'git log'

89 command to control what is shown and how. See linkgit:git-log[1].

91 -show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]::

91 +`show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]`::

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,12 +96,12 @@ show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]::

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

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>]::

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,19 +112,19 @@ Applying the state can fail with conflicts; in this case, it is not

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>]::

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>]::

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>`.

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,54 +132,51 @@ the stash entry is applied on top of the commit that was HEAD at the

132 time `git stash` was run, it restores the originally stashed state

133 with no conflicts.

134

135 -clear::

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>]::

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

144 -create::

145 -

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

152 -store::

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

159 -export ( --print | --to-ref <ref> ) [<stash>...]::

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

165 -import <commit>::

166 -

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 -------

173 --a::

174 ---all::

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

180 --u::

181 ---include-untracked::

182 ---no-include-untracked::

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`.

@@ -187,12 +184,12 @@ up with `git clean`.

184 When used with the `show` command, show the untracked files in the stash

185 entry as part of the diff.

186

190 ---only-untracked::

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

195 ---index::

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

@@ -200,15 +197,15 @@ the index's ones. However, this can fail, when you have conflicts

197 (which are stored in the index, where you therefore can no longer

198 apply the changes as they were originally).

199

203 --k::

204 ---keep-index::

205 ---no-keep-index::

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

210 --p::

211 ---patch::

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

@@ -224,8 +221,8 @@ The `--patch` option implies `--keep-index`. You can use

221

222 include::diff-context-options.adoc[]

223

227 --S::

228 ---staged::

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

@@ -234,49 +231,49 @@ of current branch.

231 +

232 The `--patch` option has priority over this one.

233

237 ---pathspec-from-file=<file>::

234 +`--pathspec-from-file=<file>`::

235 This option is only valid for `push` command.

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

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

247 ---pathspec-file-nul::

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

254 --q::

255 ---quiet::

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

261 ---print::

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

268 ---to-ref::

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

274 -\--::

271 +`--`::

272 This option is only valid for `push` command.

273 +

274 Separates pathspec from options for disambiguation purposes.

275

279 -<pathspec>...::

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

@@ -286,11 +283,11 @@ too, leaving files that do not match the pathspec intact.

283 +

284 For more details, see the 'pathspec' entry in linkgit:gitglossary[7].

285

289 -<stash>::

286 +_<stash>_::

287 This option is only valid for `apply`, `branch`, `drop`, `pop`,

288 `show`, and `export` commands.

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

291 given, the latest stash is assumed (that is, `stash@{0}`).

292

293 DISCUSSION

@@ -419,6 +416,7 @@ CONFIGURATION

416

417 include::includes/cmd-config-section-all.adoc[]

418

419 +:git-stash: 1

420 include::config/stash.adoc[]

421

422