doc: git-restore: migrate to new style format #1847
+55
−55
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
/submit |
This seems to have hit a new bug in GitGitGadget. I'm on it. |
dscho
added a commit
to dscho/gitgitgadget
that referenced
this pull request
Jan 4, 2025
I overlooked that _some_ of those do not want the second parameter to refer to a PullRequest URL, and those that do no longer need to construct it from a Pull Request Number manually (because the `OptionalRepoOwnerCommand` class does it for them). This led to errors when `/submit`ing PRs, e.g. gitgitgadget/git#1847 (comment) (https://dev.azure.com/gitgitgadget/git/_build/results?buildId=232598&view=logs&j=fd490c07-0b22-5182-fac9-6d67fe1e939b&t=28e14b79-1d95-5195-ee03-3a68ac48a418&l=13 points to the exact error): node build/script/misc-helper.js handle-pr-comment 2571259843 GET /repos/gitgitgadget/git/issues/comments/NaN - 404 with id 8FC2:20D9D0:4EF0B5D:5C1E5A8:6779306A in 536ms Let's fix these inadvertent regressions. Signed-off-by: Johannes Schindelin <[email protected]>
|
Submitted as [email protected] To fetch this version into To fetch this version to local tag |
Thank you. Should I /submit again? |
No, it was sent. |
|
On the Git mailing list, Patrick Steinhardt wrote (reply to this): 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?= <[email protected]>
>
> 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 |
|
User |
|
This patch series was integrated into seen via git@673f02c. |
|
This branch is now known as |
|
This patch series was integrated into seen via git@cfb7c35. |
|
On the Git mailing list, Jean-Noël AVILA wrote (reply to this): On Monday, 6 January 2025 07:48:27 CET Patrick Steinhardt wrote:
> 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?= <[email protected]>
> >
> > 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.
>
Will do.
> > 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.
Sorry for mixing things up revs with refs. The "A" and "B" are just
placeholders for revisions, and their names need to be more informative.
So, it should be <rev-A> and <rev-B> all along.
>
> > @@ -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.
>
For the first set of options, there is a conversion to imperative mood, and I
triggered a reflow.
For the second one, it just appears that all lines are slightly changed by
the new formatting.
More generally, I kept reflowing the paragraphs to maintain the width, because
this was done everywhere before, but I would strongly prefer having each
sentence on separate line, regardless of its length. For asciidoc texts, this
policy has some advantages:
* keep a lexical entity as a single line, and get rid messed up diffs due to
reflowing.
* unfortunate automatic reflows can create errors, for instance when a part of
text is sent to the beginning of line and is interpreted as a list item.
JN
|
|
This patch series was integrated into seen via git@ddae21b. |
|
This patch series was integrated into seen via git@b20ee10. |
- 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 <[email protected]>
jnavila
force-pushed
the
doc-git-restore
branch
from
424ddb9 to
69c01f0
Compare
|
This patch series was integrated into seen via git@b47f248. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
cc: Patrick Steinhardt [email protected]