doc: convert git-reset to new documentation 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. 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
Apr 12, 2025 at 12:20 UTC
5130704fca1eb19bc41910e6a70571f1f74794fb
1 file changed
+49
-49
Documentation/git-reset.adoc
+49
-49
@@ -7,23 +7,23 @@ git-reset - Reset current HEAD to the specified state
7
8
SYNOPSIS
9
--------
10
-[verse]
11
-'git reset' [-q] [<tree-ish>] [--] <pathspec>...
12
-'git reset' [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]
13
-'git reset' (--patch | -p) [<tree-ish>] [--] [<pathspec>...]
14
-'git reset' [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
10
+[synopsis]
11
+git reset [-q] [<tree-ish>] [--] <pathspec>...
12
+git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]
13
+git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]
14
+git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
15
16
DESCRIPTION
17
-----------
18
-In the first three forms, copy entries from `<tree-ish>` to the index.
19
-In the last form, set the current branch head (`HEAD`) to `<commit>`,
18
+In the first three forms, copy entries from _<tree-ish>_ to the index.
19
+In the last form, set the current branch head (`HEAD`) to _<commit>_,
20
optionally modifying index and working tree to match.
21
-The `<tree-ish>`/`<commit>` defaults to `HEAD` in all forms.
21
+The _<tree-ish>_/_<commit>_ defaults to `HEAD` in all forms.
22
23
-'git reset' [-q] [<tree-ish>] [--] <pathspec>...::
24
-'git reset' [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]::
23
+`git reset [-q] [<tree-ish>] [--] <pathspec>...`::
24
+`git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]`::
25
These forms reset the index entries for all paths that match the
26
- `<pathspec>` to their state at `<tree-ish>`. (It does not affect
26
+ _<pathspec>_ to their state at _<tree-ish>_. (It does not affect
27
the working tree or the current branch.)
28
+
29
This means that `git reset <pathspec>` is the opposite of `git add
@@ -37,30 +37,30 @@ and specifying a commit with `--source`, you
37
can copy the contents of a path out of a commit to the index and to the
38
working tree in one go.
39
40
-'git reset' (--patch | -p) [<tree-ish>] [--] [<pathspec>...]::
40
+`git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]`::
41
Interactively select hunks in the difference between the index
42
- and `<tree-ish>` (defaults to `HEAD`). The chosen hunks are applied
42
+ and _<tree-ish>_ (defaults to `HEAD`). The chosen hunks are applied
43
in reverse to the index.
44
+
45
This means that `git reset -p` is the opposite of `git add -p`, i.e.
46
-you can use it to selectively reset hunks. See the ``Interactive Mode''
46
+you can use it to selectively reset hunks. See the "Interactive Mode"
47
section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
48
49
-'git reset' [<mode>] [<commit>]::
50
- This form resets the current branch head to `<commit>` and
51
- possibly updates the index (resetting it to the tree of `<commit>`) and
52
- the working tree depending on `<mode>`. Before the operation, `ORIG_HEAD`
53
- is set to the tip of the current branch. If `<mode>` is omitted,
54
- defaults to `--mixed`. The `<mode>` must be one of the following:
49
+`git reset [<mode>] [<commit>]`::
50
+ This form resets the current branch head to _<commit>_ and
51
+ possibly updates the index (resetting it to the tree of _<commit>_) and
52
+ the working tree depending on _<mode>_. Before the operation, `ORIG_HEAD`
53
+ is set to the tip of the current branch. If _<mode>_ is omitted,
54
+ defaults to `--mixed`. The _<mode>_ must be one of the following:
55
+
56
--
57
---soft::
57
+`--soft`::
58
Does not touch the index file or the working tree at all (but
59
- resets the head to `<commit>`, just like all modes do). This leaves
59
+ resets the head to _<commit>_, just like all modes do). This leaves
60
all your changed files "Changes to be committed", as `git status`
61
would put it.
62
63
---mixed::
63
+`--mixed`::
64
Resets the index but not the working tree (i.e., the changed files
65
are preserved but not marked for commit) and reports what has not
66
been updated. This is the default action.
@@ -68,33 +68,33 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
68
If `-N` is specified, removed paths are marked as intent-to-add (see
69
linkgit:git-add[1]).
70
71
---hard::
71
+`--hard`::
72
Resets the index and working tree. Any changes to tracked files in the
73
- working tree since `<commit>` are discarded. Any untracked files or
73
+ working tree since _<commit>_ are discarded. Any untracked files or
74
directories in the way of writing any tracked files are simply deleted.
75
76
---merge::
76
+`--merge`::
77
Resets the index and updates the files in the working tree that are
78
- different between `<commit>` and `HEAD`, but keeps those which are
78
+ different between _<commit>_ and `HEAD`, but keeps those which are
79
different between the index and working tree (i.e. which have changes
80
which have not been added).
81
- If a file that is different between `<commit>` and the index has
81
+ If a file that is different between _<commit>_ and the index has
82
unstaged changes, reset is aborted.
83
+
84
In other words, `--merge` does something like a `git read-tree -u -m <commit>`,
85
but carries forward unmerged index entries.
86
87
---keep::
87
+`--keep`::
88
Resets index entries and updates files in the working tree that are
89
- different between `<commit>` and `HEAD`.
90
- If a file that is different between `<commit>` and `HEAD` has local
89
+ different between _<commit>_ and `HEAD`.
90
+ If a file that is different between _<commit>_ and `HEAD` has local
91
changes, reset is aborted.
92
93
---[no-]recurse-submodules::
94
- When the working tree is updated, using --recurse-submodules will
93
+`--[no-]recurse-submodules`::
94
+ When the working tree is updated, using `--recurse-submodules` will
95
also recursively reset the working tree of all active submodules
96
according to the commit recorded in the superproject, also setting
97
- the submodules' HEAD to be detached at that commit.
97
+ the submodules' `HEAD` to be detached at that commit.
98
--
99
100
See "Reset, restore and revert" in linkgit:git[1] for the differences
@@ -104,31 +104,31 @@ between the three commands.
104
OPTIONS
105
-------
106
107
--q::
108
---quiet::
107
+`-q`::
108
+`--quiet`::
109
Be quiet, only report errors.
110
111
---refresh::
112
---no-refresh::
111
+`--refresh`::
112
+`--no-refresh`::
113
Refresh the index after a mixed reset. Enabled by default.
114
115
---pathspec-from-file=<file>::
116
- Pathspec is passed in `<file>` instead of commandline args. If
117
- `<file>` is exactly `-` then standard input is used. Pathspec
118
- elements are separated by LF or CR/LF. Pathspec elements can be
115
+`--pathspec-from-file=<file>`::
116
+ Pathspec is passed in _<file>_ instead of commandline args. If
117
+ _<file>_ is exactly `-` then standard input is used. Pathspec
118
+ elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be
119
quoted as explained for the configuration variable `core.quotePath`
120
(see linkgit:git-config[1]). See also `--pathspec-file-nul` and
121
global `--literal-pathspecs`.
122
123
---pathspec-file-nul::
123
+`--pathspec-file-nul`::
124
Only meaningful with `--pathspec-from-file`. Pathspec elements are
125
- separated with NUL character and all other characters are taken
125
+ separated with _NUL_ character and all other characters are taken
126
literally (including newlines and quotes).
127
128
-\--::
128
+`--`::
129
Do not interpret any more arguments as options.
130
131
-<pathspec>...::
131
+`<pathspec>...`::
132
Limits the paths affected by the operation.
133
+
134
For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
@@ -348,7 +348,7 @@ $ git commit ... <8>
348
------------
349
+
350
<1> First, reset the history back one commit so that we remove the original
351
- commit, but leave the working tree with all the changes. The -N ensures
351
+ commit, but leave the working tree with all the changes. The `-N` ensures
352
that any new files added with `HEAD` are still marked so that `git add -p`
353
will find them.
354
<2> Next, we interactively select diff hunks to add using the `git add -p`
@@ -458,7 +458,7 @@ working index HEAD target working index HEAD
458
--keep B C C
459
....
460
461
-`reset --merge` is meant to be used when resetting out of a conflicted
461
+`git reset --merge` is meant to be used when resetting out of a conflicted
462
merge. Any mergy operation guarantees that the working tree file that is
463
involved in the merge does not have a local change with respect to the index
464
before it starts, and that it writes the result out to the working tree. So if
@@ -467,7 +467,7 @@ between the index and the working tree, then it means that we are not
467
resetting out from a state that a mergy operation left after failing
468
with a conflict. That is why we disallow `--merge` option in this case.
469
470
-`reset --keep` is meant to be used when removing some of the last
470
+`git reset --keep` is meant to be used when removing some of the last
471
commits in the current branch while keeping changes in the working
472
tree. If there could be conflicts between the changes in the commit we
473
want to remove and the changes in the working tree we want to keep,