Skip to content

doc: convert git-reset, git-rm and git-mv to new documentation format #1896

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: master
Choose a base branch
from
Open

doc: convert git-reset, git-rm and git-mv to new documentation format #1896

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
5a6c7de
doc: convert git-reset to new documentation format
jnavila Mar 28, 2025
440eac1
doc: fix synopsis analysis logic
jnavila Mar 28, 2025
6814e98
doc: convert git-rm to new documentation format
jnavila Mar 28, 2025
2a12973
doc: move synopsis git-mv commands in the synopsis section
jnavila Mar 30, 2025
1868dfc
doc: convert git-mv to new documentation format
jnavila Mar 30, 2025
2ddce76
doc: fix asciidoctor synopsis processing of triple-dots
jnavila Apr 2, 2025
2690f84
doc: add markup for characters in Guidelines
jnavila Apr 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions Documentation/CodingGuidelines
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -861,6 +861,9 @@ Markup:
_<git-dir>_
_<key-id>_

Characters are also surrounded by underscores:
_LF_, _CR_, _CR_/_LF_, _NUL_, _EOF_

Git's Asciidoc processor has been tailored to treat backticked text
as complex synopsis. When literal and placeholders are mixed, you can
use the backtick notation which will take care of correctly typesetting
Expand Down
8 changes: 4 additions & 4 deletions Documentation/asciidoc.conf.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ ifdef::doctype-book[]
endif::doctype-book[]
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Martin Ågren wrote (reply to this):

On Sun, 30 Mar 2025 at 19:16, Jean-Noël Avila via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> The synopsis analysis logic was not able to handle backslashes and stars
> which are used in the synopsis of the git-rm command. This patch fixes the
> issue by updating the regular expression used to match the keywords.

> --- a/Documentation/asciidoctor-extensions.rb.in
> +++ b/Documentation/asciidoctor-extensions.rb.in
> @@ -50,7 +50,7 @@ module Git
>        def process parent, reader, attrs
>          outlines = reader.lines.map do |l|
>            l.gsub(/(\.\.\.?)([^\]$.])/, '`\1`\2')
> -           .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$]+)}, '\1{empty}`\2`{empty}')
> +           .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$\\\*]+)}, '\1{empty}`\2`{empty}')
>             .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__')
>             .gsub(']', ']{empty}')
>          end
> @@ -72,7 +72,7 @@ module Git
>            %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)
>          elsif type == :monospaced
>            node.text.gsub(/(\.\.\.?)([^\]$.])/, '<literal>\1</literal>\2')
> -              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>')
> +              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$\\\*]+\.{0,2})+)}, '\1<literal>\2</literal>')
>                .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\1</emphasis>')
>          else
>            open, close, supports_phrase = QUOTE_TAGS[type]
> @@ -100,7 +100,7 @@ module Git
>        def convert_inline_quoted node
>          if node.type == :monospaced
>            node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2')
> -              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>')
> +              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$\\\*]+\.{0,2})+)}, '\1<code>\2</code>')
>                .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\1</em>')

This seems to introduce some extra spacing in the rendered man pages, e.g.,
"The bundle.*  keys" or "Fileglobs (e.g.  *.c)". (Asciidoctor 2.0.18.) I
haven't dug into the regexes so see what might be the cause.

(I only had time to have a look at the first patch, then briefly trying out
this one.)


Martin

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Jean-Noël Avila wrote (reply to this):

Le 05/04/2025 à 00:39, Martin Ågren a écrit :
> On Sun, 30 Mar 2025 at 19:16, Jean-Noël Avila via GitGitGadget
> <gitgitgadget@gmail.com> wrote:
>>
>> The synopsis analysis logic was not able to handle backslashes and stars
>> which are used in the synopsis of the git-rm command. This patch fixes the
>> issue by updating the regular expression used to match the keywords.
> 
>> --- a/Documentation/asciidoctor-extensions.rb.in
>> +++ b/Documentation/asciidoctor-extensions.rb.in
>> @@ -50,7 +50,7 @@ module Git
>>        def process parent, reader, attrs
>>          outlines = reader.lines.map do |l|
>>            l.gsub(/(\.\.\.?)([^\]$.])/, '`\1`\2')
>> -           .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$]+)}, '\1{empty}`\2`{empty}')
>> +           .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$\\\*]+)}, '\1{empty}`\2`{empty}')
>>             .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__')
>>             .gsub(']', ']{empty}')
>>          end
>> @@ -72,7 +72,7 @@ module Git
>>            %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)
>>          elsif type == :monospaced
>>            node.text.gsub(/(\.\.\.?)([^\]$.])/, '<literal>\1</literal>\2')
>> -              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>')
>> +              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$\\\*]+\.{0,2})+)}, '\1<literal>\2</literal>')
>>                .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\1</emphasis>')
>>          else
>>            open, close, supports_phrase = QUOTE_TAGS[type]
>> @@ -100,7 +100,7 @@ module Git
>>        def convert_inline_quoted node
>>          if node.type == :monospaced
>>            node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2')
>> -              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>')
>> +              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$\\\*]+\.{0,2})+)}, '\1<code>\2</code>')
>>                .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\1</em>')
> 
> This seems to introduce some extra spacing in the rendered man pages, e.g.,
> "The bundle.*  keys" or "Fileglobs (e.g.  *.c)". (Asciidoctor 2.0.18.) I
> haven't dug into the regexes so see what might be the cause.
> 

The xml regex seems ok for this. The docbook output is as follows:

(...)
pairs in this list are in the <literal>bundle.*</literal> namespace (see
(...)

The manpage output seems also correct:

(...)
would accept (with the
\fB\-\-file\fR
option)\&. The key\-value pairs in this list are in the
\fBbundle\&.*\fR
namespace (see
(...)

Strangely, the --file above is rendered correctly, but the bundle.*
below not. I do not know TROFF to assess what is going on. Has '*' a
special behavior in a bold span?

JN


[literal-inlinemacro]
{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@\\\*\/_^\$]+\.?)+|,)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}

endif::backend-docbook[]

Expand Down Expand Up @@ -75,18 +75,18 @@ git-relative-html-prefix=
<a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>

[literal-inlinemacro]
{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,\\\*\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}

endif::backend-xhtml11[]

ifdef::backend-docbook[]
ifdef::doctype-manpage[]
[paradef-default]
synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|&#8230;\\)!\\1<literal>\\2</literal>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<emphasis>\\0</emphasis>!g'"
synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|&#8230;\\)!\\1<literal>\\2</literal>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<emphasis>\\0</emphasis>!g'"
endif::doctype-manpage[]
endif::backend-docbook[]

ifdef::backend-xhtml11[]
[paradef-default]
synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|&#8230;\\)!\\1<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<em>\\0</em>!g'"
synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|&#8230;\\)!\\1<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<em>\\0</em>!g'"
endif::backend-xhtml11[]
12 changes: 7 additions & 5 deletions Documentation/asciidoctor-extensions.rb.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,8 @@ module Git

def process parent, reader, attrs
outlines = reader.lines.map do |l|
l.gsub(/(\.\.\.?)([^\]$.])/, '`\1`\2')
.gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$]+)}, '\1{empty}`\2`{empty}')
l.gsub(/(\.\.\.?)([^\]$\. ])/, '{empty}`\1`{empty}\2')
.gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$\\\*]+)}, '\1{empty}`\2`{empty}')
.gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__')
.gsub(']', ']{empty}')
end
Expand All @@ -71,8 +71,9 @@ module Git
# unhandled math; pass source to alt and required mathphrase element; dblatex will process alt as LaTeX math
%(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)
elsif type == :monospaced
node.text.gsub(/(\.\.\.?)([^\]$.])/, '<literal>\1</literal>\2')
.gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>')
node.text.gsub(/(\.\.\.?)([^\]$\.])/, '<literal>\1</literal>\2')
.gsub(/^\.\.\.?$/, '<literal>\0</literal>')
.gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@/_^\$\\\*]+\.{0,2})+|,)}, '\1<literal>\2</literal>')
.gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\1</emphasis>')
else
open, close, supports_phrase = QUOTE_TAGS[type]
Expand Down Expand Up @@ -100,7 +101,8 @@ module Git
def convert_inline_quoted node
if node.type == :monospaced
node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2')
.gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>')
.gsub(/^\.\.\.?$/, '<code>\0</code>')
.gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$\\\*]+\.{0,2})+)}, '\1<code>\2</code>')
.gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\1</em>')

else
Expand Down
33 changes: 16 additions & 17 deletions Documentation/git-mv.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,49 +8,48 @@ git-mv - Move or rename a file, a directory, or a symlink

SYNOPSIS
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Martin Ågren wrote (reply to this):

On Sun, 30 Mar 2025 at 19:16, Jean-Noël Avila via GitGitGadget
<gitgitgadget@gmail.com> wrote:

>  [verse]
> -'git mv' [<options>] <source>... <destination>
> +'git mv' [-v] [-f] [-n] [-k] <source> <destination>
> +'git mv' [-v] [-f] [-n] [-k] <source> ... <destination-directory>

Shouldn't "..." be tucked with the preceding "<source>", i.e.,
"<source>..." as it was in the original?

>  DESCRIPTION
>  -----------
>  Move or rename a file, directory, or symlink.
>
> - git mv [-v] [-f] [-n] [-k] <source> <destination>
> - git mv [-v] [-f] [-n] [-k] <source> ... <destination-directory>
> -

This is where "<source> ..." comes from. You moved these lines up. Good.
But I do think we want "<source>..."?

Martin

--------
[verse]
'git mv' [<options>] <source>... <destination>

[synopsis]
git mv [-v] [-f] [-n] [-k] <source> <destination>
git mv [-v] [-f] [-n] [-k] <source>... <destination-directory>

DESCRIPTION
-----------
Move or rename a file, directory, or symlink.

git mv [-v] [-f] [-n] [-k] <source> <destination>
git mv [-v] [-f] [-n] [-k] <source> ... <destination-directory>

In the first form, it renames <source>, which must exist and be either
a file, symlink or directory, to <destination>.
In the second form, the last argument has to be an existing
In the first form, it renames _<source>_, which must exist and be either
a file, symlink or directory, to _<destination>_.
In the second form, _<destination-directory>_ has to be an existing
directory; the given sources will be moved into this directory.

The index is updated after successful completion, but the change must still be
committed.

OPTIONS
-------
-f::
--force::
`-f`::
`--force`::
Force renaming or moving of a file even if the <destination> exists.
-k::
`-k`::
Skip move or rename actions which would lead to an error
condition. An error happens when a source is neither existing nor
controlled by Git, or when it would overwrite an existing
file unless `-f` is given.
-n::
--dry-run::
`-n`::
`--dry-run`::
Do nothing; only show what would happen

-v::
--verbose::
`-v`::
`--verbose`::
Report the names of files as they are moved.

SUBMODULES
----------
Moving a submodule using a gitfile (which means they were cloned
with a Git version 1.7.8 or newer) will update the gitfile and
core.worktree setting to make the submodule work in the new location.
It also will attempt to update the submodule.<name>.path setting in
the linkgit:gitmodules[5] file and stage that file (unless -n is used).
It also will attempt to update the `submodule.<name>.path` setting in
the linkgit:gitmodules[5] file and stage that file (unless `-n` is used).

BUGS
----
Expand Down
98 changes: 49 additions & 49 deletions Documentation/git-reset.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,23 +7,23 @@ git-reset - Reset current HEAD to the specified state

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Martin Ågren wrote (reply to this):

Hi Jean-Noël,

On Sun, 30 Mar 2025 at 19:16, Jean-Noël Avila via GitGitGadget
<gitgitgadget@gmail.com> wrote:

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

> ---soft::
> +`--soft`::
>         Does not touch the index file or the working tree at all (but
> -       resets the head to `<commit>`, just like all modes do). This leaves
> -       all your changed files "Changes to be committed", as `git status`
> +       resets the head to _<commit>_, just like all modes do). This leaves
> +       all your changed files "Changes to be committed", as `git status
>         would put it.

This loses the closing backtick after "git status".

> ---pathspec-from-file=<file>::
> -       Pathspec is passed in `<file>` instead of commandline args. If
> -       `<file>` is exactly `-` then standard input is used. Pathspec
> -       elements are separated by LF or CR/LF. Pathspec elements can be
> +`--pathspec-from-file=<file>`::
> +       Pathspec is passed in _<file>_ instead of commandline args. If
> +       _<file>_ is exactly `-` then standard input is used. Pathspec
> +       elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be
>         quoted as explained for the configuration variable `core.quotePath`
>         (see linkgit:git-config[1]). See also `--pathspec-file-nul` and
>         global `--literal-pathspecs`.
>
> ---pathspec-file-nul::
> +`--pathspec-file-nul`::
>         Only meaningful with `--pathspec-from-file`. Pathspec elements are
> -       separated with NUL character and all other characters are taken
> +       separated with _NUL_ character and all other characters are taken
>         literally (including newlines and quotes).

I was surprised that you wrapped CR, LF, and NUL in underscores. The
commit message only talks about <placeholders>, similar to
CodingGuidelines. That said, these _CR_ and friends seem to be
consistent with similar conversions you've done before.


Martin

SYNOPSIS
--------
[verse]
'git reset' [-q] [<tree-ish>] [--] <pathspec>...
'git reset' [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]
'git reset' (--patch | -p) [<tree-ish>] [--] [<pathspec>...]
'git reset' [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
[synopsis]
git reset [-q] [<tree-ish>] [--] <pathspec>...
git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]
git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]
git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]

DESCRIPTION
-----------
In the first three forms, copy entries from `<tree-ish>` to the index.
In the last form, set the current branch head (`HEAD`) to `<commit>`,
In the first three forms, copy entries from _<tree-ish>_ to the index.
In the last form, set the current branch head (`HEAD`) to _<commit>_,
optionally modifying index and working tree to match.
The `<tree-ish>`/`<commit>` defaults to `HEAD` in all forms.
The _<tree-ish>_/_<commit>_ defaults to `HEAD` in all forms.

'git reset' [-q] [<tree-ish>] [--] <pathspec>...::
'git reset' [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]::
`git reset [-q] [<tree-ish>] [--] <pathspec>...`::
`git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]`::
These forms reset the index entries for all paths that match the
`<pathspec>` to their state at `<tree-ish>`. (It does not affect
_<pathspec>_ to their state at _<tree-ish>_. (It does not affect
the working tree or the current branch.)
+
This means that `git reset <pathspec>` is the opposite of `git add
Expand All @@ -37,64 +37,64 @@ and specifying a commit with `--source`, you
can copy the contents of a path out of a commit to the index and to the
working tree in one go.

'git reset' (--patch | -p) [<tree-ish>] [--] [<pathspec>...]::
`git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]`::
Interactively select hunks in the difference between the index
and `<tree-ish>` (defaults to `HEAD`). The chosen hunks are applied
and _<tree-ish>_ (defaults to `HEAD`). The chosen hunks are applied
in reverse to the index.
+
This means that `git reset -p` is the opposite of `git add -p`, i.e.
you can use it to selectively reset hunks. See the ``Interactive Mode''
you can use it to selectively reset hunks. See the "Interactive Mode"
section of linkgit:git-add[1] to learn how to operate the `--patch` mode.

'git reset' [<mode>] [<commit>]::
This form resets the current branch head to `<commit>` and
possibly updates the index (resetting it to the tree of `<commit>`) and
the working tree depending on `<mode>`. Before the operation, `ORIG_HEAD`
is set to the tip of the current branch. If `<mode>` is omitted,
defaults to `--mixed`. The `<mode>` must be one of the following:
`git reset [<mode>] [<commit>]`::
This form resets the current branch head to _<commit>_ and
possibly updates the index (resetting it to the tree of _<commit>_) and
the working tree depending on _<mode>_. Before the operation, `ORIG_HEAD`
is set to the tip of the current branch. If _<mode>_ is omitted,
defaults to `--mixed`. The _<mode>_ must be one of the following:
+
--
--soft::
`--soft`::
Does not touch the index file or the working tree at all (but
resets the head to `<commit>`, just like all modes do). This leaves
resets the head to _<commit>_, just like all modes do). This leaves
all your changed files "Changes to be committed", as `git status`
would put it.

--mixed::
`--mixed`::
Resets the index but not the working tree (i.e., the changed files
are preserved but not marked for commit) and reports what has not
been updated. This is the default action.
+
If `-N` is specified, removed paths are marked as intent-to-add (see
linkgit:git-add[1]).

--hard::
`--hard`::
Resets the index and working tree. Any changes to tracked files in the
working tree since `<commit>` are discarded. Any untracked files or
working tree since _<commit>_ are discarded. Any untracked files or
directories in the way of writing any tracked files are simply deleted.

--merge::
`--merge`::
Resets the index and updates the files in the working tree that are
different between `<commit>` and `HEAD`, but keeps those which are
different between _<commit>_ and `HEAD`, but keeps those which are
different between the index and working tree (i.e. which have changes
which have not been added).
If a file that is different between `<commit>` and the index has
If a file that is different between _<commit>_ and the index has
unstaged changes, reset is aborted.
+
In other words, `--merge` does something like a `git read-tree -u -m <commit>`,
but carries forward unmerged index entries.

--keep::
`--keep`::
Resets index entries and updates files in the working tree that are
different between `<commit>` and `HEAD`.
If a file that is different between `<commit>` and `HEAD` has local
different between _<commit>_ and `HEAD`.
If a file that is different between _<commit>_ and `HEAD` has local
changes, reset is aborted.

--[no-]recurse-submodules::
When the working tree is updated, using --recurse-submodules will
`--[no-]recurse-submodules`::
When the working tree is updated, using `--recurse-submodules` will
also recursively reset the working tree of all active submodules
according to the commit recorded in the superproject, also setting
the submodules' HEAD to be detached at that commit.
the submodules' `HEAD` to be detached at that commit.
--

See "Reset, restore and revert" in linkgit:git[1] for the differences
Expand All @@ -104,31 +104,31 @@ between the three commands.
OPTIONS
-------

-q::
--quiet::
`-q`::
`--quiet`::
Be quiet, only report errors.

--refresh::
--no-refresh::
`--refresh`::
`--no-refresh`::
Refresh the index after a mixed reset. Enabled by default.

--pathspec-from-file=<file>::
Pathspec is passed in `<file>` instead of commandline args. If
`<file>` is exactly `-` then standard input is used. Pathspec
elements are separated by LF or CR/LF. Pathspec elements can be
`--pathspec-from-file=<file>`::
Pathspec is passed in _<file>_ instead of commandline args. If
_<file>_ is exactly `-` then standard input is used. Pathspec
elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be
quoted as explained for the configuration variable `core.quotePath`
(see linkgit:git-config[1]). See also `--pathspec-file-nul` and
global `--literal-pathspecs`.

--pathspec-file-nul::
`--pathspec-file-nul`::
Only meaningful with `--pathspec-from-file`. Pathspec elements are
separated with NUL character and all other characters are taken
separated with _NUL_ character and all other characters are taken
literally (including newlines and quotes).

\--::
`--`::
Do not interpret any more arguments as options.

<pathspec>...::
`<pathspec>...`::
Limits the paths affected by the operation.
+
For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
Expand Down Expand Up @@ -348,7 +348,7 @@ $ git commit ... <8>
------------
+
<1> First, reset the history back one commit so that we remove the original
commit, but leave the working tree with all the changes. The -N ensures
commit, but leave the working tree with all the changes. The `-N` ensures
that any new files added with `HEAD` are still marked so that `git add -p`
will find them.
<2> Next, we interactively select diff hunks to add using the `git add -p`
Expand Down Expand Up @@ -458,7 +458,7 @@ working index HEAD target working index HEAD
--keep B C C
....

`reset --merge` is meant to be used when resetting out of a conflicted
`git reset --merge` is meant to be used when resetting out of a conflicted
merge. Any mergy operation guarantees that the working tree file that is
involved in the merge does not have a local change with respect to the index
before it starts, and that it writes the result out to the working tree. So if
Expand All @@ -467,7 +467,7 @@ between the index and the working tree, then it means that we are not
resetting out from a state that a mergy operation left after failing
with a conflict. That is why we disallow `--merge` option in this case.

`reset --keep` is meant to be used when removing some of the last
`git reset --keep` is meant to be used when removing some of the last
commits in the current branch while keeping changes in the working
tree. If there could be conflicts between the changes in the commit we
want to remove and the changes in the working tree we want to keep,
Expand Down
Loading
Loading