On Sat, Jan 04, 2025 at 01:16:40PM +0000, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@xxxxxxx>
>
> The git-restore manpage was converted to the new documentation
> format:
Commit messages should typically use imperative style, as if asking the
code to change. For example:
Convert the git-restore(1) man page to our new documentation format.
This includes the following conversions:
- 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.
> diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt
> index 975825b44aa..541a39b5d28 100644
> --- a/Documentation/git-restore.txt
> +++ b/Documentation/git-restore.txt
> @@ -41,79 +41,79 @@ OPTIONS
> If not specified, the contents are restored from `HEAD` if `--staged` is
> given, otherwise from the index.
> +
> -As a special case, you may use `"A...B"` as a shortcut for the
> -merge base of `A` and `B` if there is exactly one merge base. You can
> -leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
> +As a special case, you may use `"<refA>...<refB>"` as a shortcut for the
> +merge base of _<refA>_ and _<refB>_ if there is exactly one merge base. You can
> +leave out at most one of _<refA>__ and _<refB>_, in which case it defaults to `HEAD`.
This change is a bit surprising to me though. Why was this renamed from
A and B to refA and refB, respectively? It should be possible for these
to be object IDs and not refs.
> @@ -122,30 +122,29 @@ in linkgit:git-checkout[1] for details.
> not be updated. Just like linkgit:git-checkout[1], this will detach
> `HEAD` of the submodule.
>
> ---overlay::
> ---no-overlay::
> - In overlay mode, the command never removes files when
> - restoring. In no-overlay mode, tracked files that do not
> - appear in the `--source` tree are removed, to make them match
> - `<tree>` exactly. The default is no-overlay mode.
> -
> ---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
> +`--overlay`::
> +`--no-overlay`::
> + In overlay mode, never remove files when restoring. In no-overlay mode,
> + remove tracked files that do not appear in the `--source` tree, to make
> + them match _<tree>_ exactly. The default is no-overlay mode.
> +
> +`--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
The reflowing of these paragraphs makes it a bit hard to see what
exactly is changing.
Thanks!
Patrick
