Doc git commit #1845
Open
Doc git commit #1845
+161
−159
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
jnavila
force-pushed
the
doc_git-commit
branch
2 times, most recently
from
73260c1 to
9f8d4e7
Compare
|
/submit |
|
Submitted as [email protected] To fetch this version into To fetch this version to local tag |
|
This patch series was integrated into seen via git@5686bb1. |
![gitgitgadget[bot]](https://avatars.githubusercontent.com/in/12836?s=60&v=4){kind=small}
| @@ -7,8 +7,8 @@ git-commit - Record changes to the repository | |||
|
|
|||
There was a problem hiding this comment.
On the Git mailing list, Patrick Steinhardt wrote (reply to this):
On Fri, Jan 03, 2025 at 01:47:24PM +0000, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
>
> The documentation for git-commit has been updated to follow the new
> documentation guidelines. The following changes have been applied to
> the series of patches:
>
> - switching 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.
>
> Additionally, some option descriptions have been turned into
> imperative mood to make them more consistent with the rest of the
> documentation.
Same comment here regarding the commit message as on the other two
series. We should use imperative mood for it, as well :)
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index c822113c111..b08a398e31d 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -58,139 +58,139 @@ summary of what is included by any of the above for the next
> --z::
> ---null::
> +`-z`::
> +`--null`::
> When showing `short` or `porcelain` status output, print the
> - filename verbatim and terminate the entries with NUL, instead of LF.
> + filename verbatim and terminate the entries with _NUL_, instead of _LF_.
> If no format is given, implies the `--porcelain` output format.
> Without the `-z` option, filenames with "unusual" characters are
> quoted as explained for the configuration variable `core.quotePath`
> (see linkgit:git-config[1]).
>
> --F <file>::
> ---file=<file>::
> - Take the commit message from the given file. Use '-' to
> +`-F <file>`::
> +`--file=<file>`::
> + Take the commit message from _<file>_. Use `-` to
I think it would make sense to move changes like this, where the actual
wording changes, into a separate commit. That'd make it way easier to
spot the non-mechanical changes from those that may require some
discussion.
> @@ -257,19 +256,18 @@ default::
> The default can be changed by the `commit.cleanup` configuration
> variable (see linkgit:git-config[1]).
>
> --e::
> ---edit::
> - The message taken from file with `-F`, command line with
> - `-m`, and from commit object with `-C` are usually used as
> - the commit log message unmodified. This option lets you
> - further edit the message taken from these sources.
> +`-e`::
> +`--edit`::
> + Let the user further edit the message taken from file
There's a double space here. I was also wondering whether this should
say _<file>_ here to further clarify that this refers to the same
placeholder as the placeholder in `-F`. Might be confusing though, I
dunno.
> diff --git a/builtin/commit.c b/builtin/commit.c
> index ef5e622c077..a7315ed67cc 100644
> --- a/builtin/commit.c
> +++ b/builtin/commit.c
> @@ -44,7 +44,7 @@
> #include "trailer.h"
>
> static const char * const builtin_commit_usage[] = {
> - N_("git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]\n"
> + N_("git commit [-a | --interactive | --patch] [-s] [-v] [-u[<mode>]] [--amend]\n"
> " [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>]\n"
> " [-F <file> | -m <msg>] [--reset-author] [--allow-empty]\n"
> " [--allow-empty-message] [--no-verify] [-e] [--author=<author>]\n"
I guess this change is required to make t0450 happy?
PatrickThere was a problem hiding this comment.
On the Git mailing list, Jean-Noël AVILA wrote (reply to this):
Le lundi 6 janvier 2025, 08:38:19 CET Patrick Steinhardt a écrit :
> On Fri, Jan 03, 2025 at 01:47:24PM +0000, Jean-Noël Avila via GitGitGadget
wrote:
> > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
> >
> > The documentation for git-commit has been updated to follow the new
> > documentation guidelines. The following changes have been applied to
> > the series of patches:
> >
> > - switching 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.
> >
> > Additionally, some option descriptions have been turned into
> > imperative mood to make them more consistent with the rest of the
> > documentation.
>
> Same comment here regarding the commit message as on the other two
> series. We should use imperative mood for it, as well :)
Thanks for reviewing.
Being consistent with myself is imperative ;-)
>
> > diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> > index c822113c111..b08a398e31d 100644
> > --- a/Documentation/git-commit.txt
> > +++ b/Documentation/git-commit.txt
> > @@ -58,139 +58,139 @@ summary of what is included by any of the above for
the next
> > --z::
> > ---null::
> > +`-z`::
> > +`--null`::
> > When showing `short` or `porcelain` status output, print the
> > - filename verbatim and terminate the entries with NUL, instead of
LF.
> > + filename verbatim and terminate the entries with _NUL_, instead of
_LF_.
> > If no format is given, implies the `--porcelain` output format.
> > Without the `-z` option, filenames with "unusual" characters are
> > quoted as explained for the configuration variable
`core.quotePath`
> > (see linkgit:git-config[1]).
> >
> > --F <file>::
> > ---file=<file>::
> > - Take the commit message from the given file. Use '-' to
> > +`-F <file>`::
> > +`--file=<file>`::
> > + Take the commit message from _<file>_. Use `-` to
>
> I think it would make sense to move changes like this, where the actual
> wording changes, into a separate commit. That'd make it way easier to
> spot the non-mechanical changes from those that may require some
> discussion.
True. There are other parts where I introduced the place holder as an echo to
the option description. The idea is to be less verbose and more contextual.
>
> > @@ -257,19 +256,18 @@ default::
> > The default can be changed by the `commit.cleanup` configuration
> > variable (see linkgit:git-config[1]).
> >
> > --e::
> > ---edit::
> > - The message taken from file with `-F`, command line with
> > - `-m`, and from commit object with `-C` are usually used as
> > - the commit log message unmodified. This option lets you
> > - further edit the message taken from these sources.
> > +`-e`::
> > +`--edit`::
> > + Let the user further edit the message taken from file
>
> There's a double space here. I was also wondering whether this should
> say _<file>_ here to further clarify that this refers to the same
> placeholder as the placeholder in `-F`. Might be confusing though, I
> dunno.
This would sound a bit repetitive, but it is still better than making the
reader refer to the entries for each option, in which case I would also add
the placeholders when listing the options.
>
> > diff --git a/builtin/commit.c b/builtin/commit.c
> > index ef5e622c077..a7315ed67cc 100644
> > --- a/builtin/commit.c
> > +++ b/builtin/commit.c
> > @@ -44,7 +44,7 @@
> > #include "trailer.h"
> >
> > static const char * const builtin_commit_usage[] = {
> > - N_("git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>]
[--amend]\n"
> > + N_("git commit [-a | --interactive | --patch] [-s] [-v] [-
u[<mode>]] [--amend]\n"
> > " [--dry-run] [(-c | -C | --squash) <commit> | --
fixup [(amend|reword):]<commit>]\n"
> > " [-F <file> | -m <msg>] [--reset-author] [--allow-
empty]\n"
> > " [--allow-empty-message] [--no-verify] [-e] [--
author=<author>]\n"
>
> I guess this change is required to make t0450 happy?
Yes it is. To be honest, I was about to try to complete the synopsis for all
commands, but finally let this task for another round, because I'm not even
clear on what is alternative and what can be combined.
>
> Patrick
>
>
|
User |
|
This branch is now known as |
|
This patch series was integrated into seen via git@3ba590d. |
|
There was a status update in the "Cooking" section about the branch Doc updates. source: <[email protected]> |
|
This patch series was integrated into seen via git@6ae1eb3. |
|
This patch series was integrated into seen via git@ddd9fe1. |
|
This patch series was integrated into seen via git@85cb907. |
|
This patch series was integrated into seen via git@c032f5d. |
|
This patch series was integrated into seen via git@24029ce. |
|
This patch series was integrated into seen via git@a67cc3e. |
|
This patch series was integrated into seen via git@7a83a29. |
|
There was a status update in the "Cooking" section about the branch Doc updates. source: <[email protected]> |
|
This patch series was integrated into seen via git@d72664d. |
|
This patch series was integrated into seen via git@6197fd3. |
|
There was a status update in the "Cooking" section about the branch Doc updates. source: <[email protected]> |
jnavila
force-pushed
the
doc_git-commit
branch
2 times, most recently
from
3da6242 to
9d569a3
Compare
|
This patch series was integrated into seen via git@0ec2ef9. |
- 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 <[email protected]>
Fix the synopsis to reflect the option description. Signed-off-by: Jean-Noël Avila <[email protected]>
- Use imperative mood - make use of the placeholder format to simplify style Signed-off-by: Jean-Noël Avila <[email protected]>
Also prevent git-commit manpage to refer to itself in the config description by using a variable. Signed-off-by: Jean-Noël Avila <[email protected]>
Signed-off-by: Jean-Noël Avila <[email protected]>
jnavila
force-pushed
the
doc_git-commit
branch
from
9d569a3 to
28316a7
Compare
|
/submit |
|
Submitted as [email protected] To fetch this version into To fetch this version to local tag |
| @@ -7,8 +7,8 @@ git-commit - Record changes to the repository | |||
|
|
|||
There was a problem hiding this comment.
On the Git mailing list, Junio C Hamano wrote (reply to this):
"Jean-Noël Avila via GitGitGadget" <[email protected]> writes:
> -[verse]
> -'git commit' [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]
> +[synopsis]
> +git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]
> [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>]
> [-F <file> | -m <msg>] [--reset-author] [--allow-empty]
> [--allow-empty-message] [--no-verify] [-e] [--author=<author>]
It is already nice enough that with just writing [synopsis] we do
not have to worry about backquoting literals emphasising
<placeholders> and other mark-up minutiae. And then ...
> --C <commit>::
> ---reuse-message=<commit>::
> - Take an existing commit object, and reuse the log message
> +`-C <commit>`::
> +`--reuse-message=<commit>`::
... we also are freed from the same worry whenever we use `here are
things that are treated pretty much the same way as in [synopsis]
section` notation like here. Quite nice.
> @@ -507,12 +507,12 @@ COMMIT INFORMATION
> Author and committer information is taken from the following environment
> variables, if set:
>
> - GIT_AUTHOR_NAME
> - GIT_AUTHOR_EMAIL
> - GIT_AUTHOR_DATE
> - GIT_COMMITTER_NAME
> - GIT_COMMITTER_EMAIL
> - GIT_COMMITTER_DATE
> + * `GIT_AUTHOR_NAME`
> + * `GIT_AUTHOR_EMAIL`
> + * `GIT_AUTHOR_DATE`
> + * `GIT_COMMITTER_NAME`
> + * `GIT_COMMITTER_EMAIL`
> + * `GIT_COMMITTER_DATE`
OK.
| @@ -1,29 +1,34 @@ | |||
| commit.cleanup:: | |||
| ifdef::git-commit[] | |||
There was a problem hiding this comment.
On the Git mailing list, Junio C Hamano wrote (reply to this):
"Jean-Noël Avila via GitGitGadget" <[email protected]> writes:
> +ifdef::git-commit[]
> +:see-git-commit:
> +endif::git-commit[]
> +ifndef::git-commit[]
> +:see-git-commit: See linkgit:git-commit[1] for details.
> +endif::git-commit[]
> +`commit.cleanup`::
> This setting overrides the default of the `--cleanup` option in
> - `git commit`. See linkgit:git-commit[1] for details. Changing the
> - default can be useful when you always want to keep lines that begin
> + `git commit`. {see-git-commit} Changing the default can be useful
> + when you always want to keep lines that begin
OK.
|
This patch series was integrated into seen via git@65ba427. |
| @@ -34,7 +34,7 @@ project find it more convenient to use legacy encodings, Git | |||
| does not forbid it. However, there are a few things to keep in | |||
There was a problem hiding this comment.
On the Git mailing list, Patrick Steinhardt wrote (reply to this):
On Wed, Jan 15, 2025 at 08:23:48PM +0000, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
I would've liked to see a small description of what this does and also
provide a bit more context in the other commit messages instead of the
bulleted lists you have. They don't give the reader much of a sense of
the context we're operating in and why we think that those changes are
good.
Other than that the patch series looks fine to me. Thanks!
Patrick
|
This patch series was integrated into seen via git@567a7b7. |
|
This patch series was integrated into seen via git@6234ee9. |
|
This patch series was integrated into seen via git@f65a493. |
|
There was a status update in the "Cooking" section about the branch Doc updates. Will merge to 'next'? source: <[email protected]> |
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.
This series continues the effort of rewriting the documentation with uniformization and better formatting of the man pages. This time, git-commit is processed, taking advantage of previous experiences.
cc: Patrick Steinhardt [email protected]