doc: convert git-restore to new style format
- 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. While at it, also convert an option description to imperative mood. 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
Jan 10, 2025 at 10:09 UTC
69666e6746e4e87535ebf89c463980a9c655bae7
1 file changed
+55
-55
Documentation/git-restore.txt
+55
-55
@@ -7,10 +7,10 @@ git-restore - Restore working tree files
7
8
SYNOPSIS
9
--------
10
-[verse]
11
-'git restore' [<options>] [--source=<tree>] [--staged] [--worktree] [--] <pathspec>...
12
-'git restore' [<options>] [--source=<tree>] [--staged] [--worktree] --pathspec-from-file=<file> [--pathspec-file-nul]
13
-'git restore' (-p|--patch) [<options>] [--source=<tree>] [--staged] [--worktree] [--] [<pathspec>...]
10
+[synopsis]
11
+git restore [<options>] [--source=<tree>] [--staged] [--worktree] [--] <pathspec>...
12
+git restore [<options>] [--source=<tree>] [--staged] [--worktree] --pathspec-from-file=<file> [--pathspec-file-nul]
13
+git restore (-p|--patch) [<options>] [--source=<tree>] [--staged] [--worktree] [--] [<pathspec>...]
14
15
DESCRIPTION
16
-----------
@@ -32,8 +32,8 @@ THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
32
33
OPTIONS
34
-------
35
--s <tree>::
36
---source=<tree>::
35
+`-s <tree>`::
36
+`--source=<tree>`::
37
Restore the working tree files with the content from the given
38
tree. It is common to specify the source tree by naming a
39
commit, branch or tag associated with it.
@@ -41,79 +41,79 @@ OPTIONS
41
If not specified, the contents are restored from `HEAD` if `--staged` is
42
given, otherwise from the index.
43
+
44
-As a special case, you may use `"A...B"` as a shortcut for the
45
-merge base of `A` and `B` if there is exactly one merge base. You can
46
-leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
44
+As a special case, you may use `"<rev-A>...<rev-B>"` as a shortcut for the
45
+merge base of _<rev-A>_ and _<rev-B>_ if there is exactly one merge base. You can
46
+leave out at most one of _<rev-A>__ and _<rev-B>_, in which case it defaults to `HEAD`.
47
48
--p::
49
---patch::
48
+`-p`::
49
+`--patch`::
50
Interactively select hunks in the difference between the
51
- restore source and the restore location. See the ``Interactive
52
- Mode'' section of linkgit:git-add[1] to learn how to operate
51
+ restore source and the restore location. See the "Interactive
52
+ Mode" section of linkgit:git-add[1] to learn how to operate
53
the `--patch` mode.
54
+
55
Note that `--patch` can accept no pathspec and will prompt to restore
56
all modified paths.
57
58
--W::
59
---worktree::
60
--S::
61
---staged::
58
+`-W`::
59
+`--worktree`::
60
+`-S`::
61
+`--staged`::
62
Specify the restore location. If neither option is specified,
63
by default the working tree is restored. Specifying `--staged`
64
will only restore the index. Specifying both restores both.
65
66
--q::
67
---quiet::
66
+`-q`::
67
+`--quiet`::
68
Quiet, suppress feedback messages. Implies `--no-progress`.
69
70
---progress::
71
---no-progress::
70
+`--progress`::
71
+`--no-progress`::
72
Progress status is reported on the standard error stream
73
by default when it is attached to a terminal, unless `--quiet`
74
is specified. This flag enables progress reporting even if not
75
attached to a terminal, regardless of `--quiet`.
76
77
---ours::
78
---theirs::
77
+`--ours`::
78
+`--theirs`::
79
When restoring files in the working tree from the index, use
80
- stage #2 ('ours') or #3 ('theirs') for unmerged paths.
80
+ stage #2 (`ours`) or #3 (`theirs`) for unmerged paths.
81
This option cannot be used when checking out paths from a
82
tree-ish (i.e. with the `--source` option).
83
+
84
-Note that during `git rebase` and `git pull --rebase`, 'ours' and
85
-'theirs' may appear swapped. See the explanation of the same options
84
+Note that during `git rebase` and `git pull --rebase`, `ours` and
85
+`theirs` may appear swapped. See the explanation of the same options
86
in linkgit:git-checkout[1] for details.
87
88
--m::
89
---merge::
88
+`-m`::
89
+`--merge`::
90
When restoring files on the working tree from the index,
91
recreate the conflicted merge in the unmerged paths.
92
This option cannot be used when checking out paths from a
93
tree-ish (i.e. with the `--source` option).
94
95
---conflict=<style>::
95
+`--conflict=<style>`::
96
The same as `--merge` option above, but changes the way the
97
conflicting hunks are presented, overriding the
98
`merge.conflictStyle` configuration variable. Possible values
99
- are "merge" (default), "diff3", and "zdiff3".
99
+ are `merge` (default), `diff3`, and `zdiff3`.
100
101
---ignore-unmerged::
101
+`--ignore-unmerged`::
102
When restoring files on the working tree from the index, do
103
not abort the operation if there are unmerged entries and
104
neither `--ours`, `--theirs`, `--merge` or `--conflict` is
105
specified. Unmerged paths on the working tree are left alone.
106
107
---ignore-skip-worktree-bits::
107
+`--ignore-skip-worktree-bits`::
108
In sparse checkout mode, the default is to only update entries
109
- matched by `<pathspec>` and sparse patterns in
110
- $GIT_DIR/info/sparse-checkout. This option ignores the sparse
109
+ matched by _<pathspec>_ and sparse patterns in
110
+ `$GIT_DIR/info/sparse-checkout`. This option ignores the sparse
111
patterns and unconditionally restores any files in
112
- `<pathspec>`.
112
+ _<pathspec>_.
113
114
---recurse-submodules::
115
---no-recurse-submodules::
116
- If `<pathspec>` names an active submodule and the restore location
114
+`--recurse-submodules`::
115
+`--no-recurse-submodules`::
116
+ If _<pathspec>_ names an active submodule and the restore location
117
includes the working tree, the submodule will only be updated if
118
this option is given, in which case its working tree will be
119
restored to the commit recorded in the superproject, and any local
@@ -122,30 +122,30 @@ in linkgit:git-checkout[1] for details.
122
not be updated. Just like linkgit:git-checkout[1], this will detach
123
`HEAD` of the submodule.
124
125
---overlay::
126
---no-overlay::
127
- In overlay mode, the command never removes files when
128
- restoring. In no-overlay mode, tracked files that do not
129
- appear in the `--source` tree are removed, to make them match
130
- `<tree>` exactly. The default is no-overlay mode.
131
-
132
---pathspec-from-file=<file>::
133
- Pathspec is passed in `<file>` instead of commandline args. If
134
- `<file>` is exactly `-` then standard input is used. Pathspec
135
- elements are separated by LF or CR/LF. Pathspec elements can be
125
+`--overlay`::
126
+`--no-overlay`::
127
+ In overlay mode, never remove files when restoring. In no-overlay mode,
128
+ remove tracked files that do not appear in the _<tree>_ of
129
+ `--source=<tree>`, to make them match _<tree>_ exactly. The default
130
+ is no-overlay mode.
131
+
132
+`--pathspec-from-file=<file>`::
133
+ Pathspec is passed in _<file>_ instead of commandline args. If
134
+ _<file>_ is exactly `-` then standard input is used. Pathspec
135
+ elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be
136
quoted as explained for the configuration variable `core.quotePath`
137
(see linkgit:git-config[1]). See also `--pathspec-file-nul` and
138
global `--literal-pathspecs`.
139
140
---pathspec-file-nul::
140
+`--pathspec-file-nul`::
141
Only meaningful with `--pathspec-from-file`. Pathspec elements are
142
- separated with NUL character and all other characters are taken
142
+ separated with _NUL_ character and all other characters are taken
143
literally (including newlines and quotes).
144
145
-\--::
145
+`--`::
146
Do not interpret any more arguments as options.
147
148
-<pathspec>...::
148
+`<pathspec>...`::
149
Limits the paths affected by the operation.
150
+
151
For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
@@ -154,7 +154,7 @@ EXAMPLES
154
--------
155
156
The following sequence switches to the `master` branch, reverts the
157
-`Makefile` to two revisions back, deletes hello.c by mistake, and gets
157
+`Makefile` to two revisions back, deletes `hello.c` by mistake, and gets
158
it back from the index.
159
160
------------
@@ -165,7 +165,7 @@ $ git restore hello.c <2>
165
------------
166
167
<1> take a file out of another commit
168
-<2> restore hello.c from the index
168
+<2> restore `hello.c` from the index
169
170
If you want to restore _all_ C source files to match the version in
171
the index, you can say