* [PATCH 0/4] A handful of doc synopsis/options update
@ 2025-05-01 21:34 Junio C Hamano
2025-05-01 21:34 ` [PATCH 1/4] git-verify-* doc: update mark-up of synopsis option descriptions Junio C Hamano
` (5 more replies)
0 siblings, 6 replies; 26+ messages in thread
From: Junio C Hamano @ 2025-05-01 21:34 UTC (permalink / raw)
To: git
Continuing what Jean-Noël started with 22293895 (doc: apply synopsis
simplification on git-clone and git-init, 2024-09-24), use more
[synopsis] (rather than [verse]) mark-up and also make sure
- dashed options in the text, including the heading for enumerated
dashed options in the OPTIONS section, are `backquoted` to be
typeset verbatim.
- both positive and negative variants are spelled out when the
option is negatable, i.e. a heading "--[no-]opt::" is separated
into "--opt::" and "--no-opt::", to help grep hit with simpler
patterns.
- non-options are not described in the OPTIONS section.
The "git worktree" one is a bit unsatisfactory and should be
considered WIP.
Junio C Hamano (4):
git-verify-* doc: update mark-up of synopsis option descriptions
git-{var,write-tree} docs: update mark-up of synopsis option
descriptions
git-daemon doc: update mark-up of synopsis option descriptions
git-worktree doc: update mark-up of synopsis option descriptions
Documentation/git-daemon.adoc | 107 ++++++++++++++-------------
Documentation/git-var.adoc | 6 +-
Documentation/git-verify-commit.adoc | 16 ++--
Documentation/git-verify-pack.adoc | 28 +++----
Documentation/git-verify-tag.adoc | 16 ++--
Documentation/git-worktree.adoc | 71 +++++++++---------
Documentation/git-write-tree.adoc | 16 ++--
7 files changed, 129 insertions(+), 131 deletions(-)
--
2.49.0-599-g90c2cffacf
^ permalink raw reply [flat|nested] 26+ messages in thread* [PATCH 1/4] git-verify-* doc: update mark-up of synopsis option descriptions 2025-05-01 21:34 [PATCH 0/4] A handful of doc synopsis/options update Junio C Hamano @ 2025-05-01 21:34 ` Junio C Hamano 2025-05-01 22:43 ` Eric Sunshine 2025-05-01 21:34 ` [PATCH 2/4] git-{var,write-tree} docs: " Junio C Hamano ` (4 subsequent siblings) 5 siblings, 1 reply; 26+ messages in thread From: Junio C Hamano @ 2025-05-01 21:34 UTC (permalink / raw) To: git To unify mark-up used in our documentation to a newer convention, started by 22293895 (doc: apply synopsis simplification on git-clone and git-init, 2024-09-24), update the documentation pages for 'git verify-commit', 'git verify-tag', and 'git verify-pack' to * use [synopsis], not [verse] in the SYNOPSIS section * enclose `--option=<value>` in backquotes * do not describe non-option arguments in the OPTIONS section Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/git-verify-commit.adoc | 16 +++++++--------- Documentation/git-verify-pack.adoc | 28 ++++++++++++---------------- Documentation/git-verify-tag.adoc | 16 +++++++--------- 3 files changed, 26 insertions(+), 34 deletions(-) diff --git a/Documentation/git-verify-commit.adoc b/Documentation/git-verify-commit.adoc index aee4c40eac..ff5b8b97ef 100644 --- a/Documentation/git-verify-commit.adoc +++ b/Documentation/git-verify-commit.adoc @@ -7,26 +7,24 @@ git-verify-commit - Check the GPG signature of commits SYNOPSIS -------- -[verse] -'git verify-commit' [-v | --verbose] [--raw] <commit>... +[synopsis] +git verify-commit [-v | --verbose] [--raw] <commit>... DESCRIPTION ----------- -Validates the GPG signature created by 'git commit -S'. +Validates the GPG signature created by `git commit -S` +on the commit objects given on the command line. OPTIONS ------- ---raw:: +`--raw`:: Print the raw gpg status output to standard error instead of the normal human-readable output. --v:: ---verbose:: +`-v`:: +`--verbose`:: Print the contents of the commit object before validating it. -<commit>...:: - SHA-1 identifiers of Git commit objects. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-verify-pack.adoc b/Documentation/git-verify-pack.adoc index d7e886918a..b0462d8db3 100644 --- a/Documentation/git-verify-pack.adoc +++ b/Documentation/git-verify-pack.adoc @@ -8,43 +8,39 @@ git-verify-pack - Validate packed Git archive files SYNOPSIS -------- -[verse] -'git verify-pack' [-v | --verbose] [-s | --stat-only] [--] <pack>.idx... +[synopsis] +git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx... DESCRIPTION ----------- -Reads given idx file for packed Git archive created with the -'git pack-objects' command and verifies the idx file and the -corresponding pack file. +Read each idx file for packed Git archive given on the command line, +and verify the idx file and the corresponding pack file. OPTIONS ------- -<pack>.idx ...:: - The idx files to verify. - --v:: ---verbose:: +`-v`:: +`--verbose`:: After verifying the pack, show the list of objects contained in the pack and a histogram of delta chain length. --s:: ---stat-only:: +`-s`:: +`--stat-only`:: Do not verify the pack contents; only show the histogram of delta chain length. With `--verbose`, the list of objects is also shown. -\--:: +`--`:: Do not interpret any more arguments as options. OUTPUT FORMAT ------------- -When specifying the -v option the format used is: +When specifying the `-v` option the format used is: - SHA-1 type size size-in-packfile offset-in-packfile + object-name type size size-in-packfile offset-in-packfile for objects that are not deltified in the pack, and - SHA-1 type size size-in-packfile offset-in-packfile depth base-SHA-1 + object-name type size size-in-packfile offset-in-packfile depth base-object-name for objects that are deltified. diff --git a/Documentation/git-verify-tag.adoc b/Documentation/git-verify-tag.adoc index 81d50ecc4c..ec995323f6 100644 --- a/Documentation/git-verify-tag.adoc +++ b/Documentation/git-verify-tag.adoc @@ -7,26 +7,24 @@ git-verify-tag - Check the GPG signature of tags SYNOPSIS -------- -[verse] -'git verify-tag' [-v | --verbose] [--format=<format>] [--raw] <tag>... +[synopsis] +git verify-tag [-v | --verbose] [--format=<format>] [--raw] <tag>... DESCRIPTION ----------- -Validates the gpg signature created by 'git tag'. +Validates the gpg signature created by 'git tag' in the tag +objects listed on the command line. OPTIONS ------- ---raw:: +`--raw`:: Print the raw gpg status output to standard error instead of the normal human-readable output. --v:: ---verbose:: +`-v`:: +`--verbose`:: Print the contents of the tag object before validating it. -<tag>...:: - SHA-1 identifiers of Git tag objects. - GIT --- Part of the linkgit:git[1] suite -- 2.49.0-599-g90c2cffacf ^ permalink raw reply related [flat|nested] 26+ messages in thread
* Re: [PATCH 1/4] git-verify-* doc: update mark-up of synopsis option descriptions 2025-05-01 21:34 ` [PATCH 1/4] git-verify-* doc: update mark-up of synopsis option descriptions Junio C Hamano @ 2025-05-01 22:43 ` Eric Sunshine 2025-05-01 23:10 ` Junio C Hamano 0 siblings, 1 reply; 26+ messages in thread From: Eric Sunshine @ 2025-05-01 22:43 UTC (permalink / raw) To: Junio C Hamano; +Cc: git On Thu, May 1, 2025 at 5:34 PM Junio C Hamano <gitster@pobox.com> wrote: > To unify mark-up used in our documentation to a newer convention, > started by 22293895 (doc: apply synopsis simplification on git-clone > and git-init, 2024-09-24), update the documentation pages for 'git > verify-commit', 'git verify-tag', and 'git verify-pack' to > > * use [synopsis], not [verse] in the SYNOPSIS section > * enclose `--option=<value>` in backquotes > * do not describe non-option arguments in the OPTIONS section > > Signed-off-by: Junio C Hamano <gitster@pobox.com> > --- > diff --git a/Documentation/git-verify-commit.adoc b/Documentation/git-verify-commit.adoc > @@ -7,26 +7,24 @@ git-verify-commit - Check the GPG signature of commits > -Validates the GPG signature created by 'git commit -S'. > +Validates the GPG signature created by `git commit -S` > +on the commit objects given on the command line. Taking note of the casing of GPG (all uppercase)... > diff --git a/Documentation/git-verify-pack.adoc b/Documentation/git-verify-pack.adoc > @@ -8,43 +8,39 @@ git-verify-pack - Validate packed Git archive files > -Reads given idx file for packed Git archive created with the > -'git pack-objects' command and verifies the idx file and the > -corresponding pack file. > +Read each idx file for packed Git archive given on the command line, > +and verify the idx file and the corresponding pack file. Okay, rewrite seems reasonable. Do we want to backtick "idx" and "pack"? > OUTPUT FORMAT > ------------- > -When specifying the -v option the format used is: > +When specifying the `-v` option the format used is: > > - SHA-1 type size size-in-packfile offset-in-packfile > + object-name type size size-in-packfile offset-in-packfile Do we not typically call this object-ID (OID) rather than object-name? > diff --git a/Documentation/git-verify-tag.adoc b/Documentation/git-verify-tag.adoc > @@ -7,26 +7,24 @@ git-verify-tag - Check the GPG signature of tags ...all uppercase GPG... > -Validates the gpg signature created by 'git tag'. > +Validates the gpg signature created by 'git tag' in the tag > +objects listed on the command line. ...since this is being rewritten anyhow, it probably would make sense to employ consistent casing of GPG. ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH 1/4] git-verify-* doc: update mark-up of synopsis option descriptions 2025-05-01 22:43 ` Eric Sunshine @ 2025-05-01 23:10 ` Junio C Hamano 0 siblings, 0 replies; 26+ messages in thread From: Junio C Hamano @ 2025-05-01 23:10 UTC (permalink / raw) To: Eric Sunshine; +Cc: git Eric Sunshine <sunshine@sunshineco.com> writes: >> -'git pack-objects' command and verifies the idx file and the >> -corresponding pack file. >> +Read each idx file for packed Git archive given on the command line, >> +and verify the idx file and the corresponding pack file. > > Okay, rewrite seems reasonable. Do we want to backtick "idx" and "pack"? No. I would understand if it is spelled '.idx', to refer to a concrete file suffix that people would type verbatim. In this sentence, however, I think "idx file" and "pack file" are used as a general noun. >> OUTPUT FORMAT >> ------------- >> -When specifying the -v option the format used is: >> +When specifying the `-v` option the format used is: >> >> - SHA-1 type size size-in-packfile offset-in-packfile >> + object-name type size size-in-packfile offset-in-packfile > > Do we not typically call this object-ID (OID) rather than object-name? Given these entries in Documentation/glossary-content.adoc [[def_hash]]hash:: In Git's context, synonym for <<def_object_name,object name>>. [[def_object_identifier]]object identifier (oid):: Synonym for <<def_object_name,object name>>. I do not think so, and if we find somebody doing so, we should correct them. >> diff --git a/Documentation/git-verify-tag.adoc b/Documentation/git-verify-tag.adoc >> @@ -7,26 +7,24 @@ git-verify-tag - Check the GPG signature of tags > > ...all uppercase GPG... > >> -Validates the gpg signature created by 'git tag'. >> +Validates the gpg signature created by 'git tag' in the tag >> +objects listed on the command line. > > ...since this is being rewritten anyhow, it probably would make sense > to employ consistent casing of GPG. Once the dust settles from this series, yes, but not in this series that is about mark-up. Thanks. ^ permalink raw reply [flat|nested] 26+ messages in thread
* [PATCH 2/4] git-{var,write-tree} docs: update mark-up of synopsis option descriptions 2025-05-01 21:34 [PATCH 0/4] A handful of doc synopsis/options update Junio C Hamano 2025-05-01 21:34 ` [PATCH 1/4] git-verify-* doc: update mark-up of synopsis option descriptions Junio C Hamano @ 2025-05-01 21:34 ` Junio C Hamano 2025-05-01 21:34 ` [PATCH 3/4] git-daemon doc: " Junio C Hamano ` (3 subsequent siblings) 5 siblings, 0 replies; 26+ messages in thread From: Junio C Hamano @ 2025-05-01 21:34 UTC (permalink / raw) To: git To unify mark-up used in our documentation to a newer convention, started by 22293895 (doc: apply synopsis simplification on git-clone and git-init, 2024-09-24), update the documentation for 'git var' and 'git write-tree' to * use [synopsis], not [verse] in the SYNOPSIS section * enclose `--option=<value>` in backquotes Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/git-var.adoc | 6 +++--- Documentation/git-write-tree.adoc | 16 ++++++++-------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/Documentation/git-var.adoc b/Documentation/git-var.adoc index 0680568dfd..909963b1c2 100644 --- a/Documentation/git-var.adoc +++ b/Documentation/git-var.adoc @@ -8,8 +8,8 @@ git-var - Show a Git logical variable SYNOPSIS -------- -[verse] -'git var' (-l | <variable>) +[synopsis] +git var (-l | <variable>) DESCRIPTION ----------- @@ -18,7 +18,7 @@ no value. OPTIONS ------- --l:: +`-l`:: Display the logical variables. In addition, all the variables of the Git configuration file .git/config are listed as well. (However, the configuration variables listing functionality diff --git a/Documentation/git-write-tree.adoc b/Documentation/git-write-tree.adoc index f22041a9dc..4e1c3b9c0c 100644 --- a/Documentation/git-write-tree.adoc +++ b/Documentation/git-write-tree.adoc @@ -8,8 +8,8 @@ git-write-tree - Create a tree object from the current index SYNOPSIS -------- -[verse] -'git write-tree' [--missing-ok] [--prefix=<prefix>/] +[synopsis] +git write-tree [--missing-ok] [--prefix=<prefix>/] DESCRIPTION ----------- @@ -18,21 +18,21 @@ tree object is printed to standard output. The index must be in a fully merged state. -Conceptually, 'git write-tree' sync()s the current index contents +Conceptually, `git write-tree` sync()s the current index contents into a set of tree files. In order to have that match what is actually in your directory right -now, you need to have done a 'git update-index' phase before you did the -'git write-tree'. +now, you need to have done a `git update-index` phase before you did the +`git write-tree`. OPTIONS ------- ---missing-ok:: - Normally 'git write-tree' ensures that the objects referenced by the +`--missing-ok`:: + Normally `git write-tree` ensures that the objects referenced by the directory exist in the object database. This option disables this check. ---prefix=<prefix>/:: +`--prefix=<prefix>/`:: Writes a tree object that represents a subdirectory `<prefix>`. This can be used to write the tree object for a subproject that is in the named subdirectory. -- 2.49.0-599-g90c2cffacf ^ permalink raw reply related [flat|nested] 26+ messages in thread
* [PATCH 3/4] git-daemon doc: update mark-up of synopsis option descriptions 2025-05-01 21:34 [PATCH 0/4] A handful of doc synopsis/options update Junio C Hamano 2025-05-01 21:34 ` [PATCH 1/4] git-verify-* doc: update mark-up of synopsis option descriptions Junio C Hamano 2025-05-01 21:34 ` [PATCH 2/4] git-{var,write-tree} docs: " Junio C Hamano @ 2025-05-01 21:34 ` Junio C Hamano 2025-05-01 22:52 ` Eric Sunshine 2025-05-01 21:34 ` [WIP PATCH 4/4] git-worktree " Junio C Hamano ` (2 subsequent siblings) 5 siblings, 1 reply; 26+ messages in thread From: Junio C Hamano @ 2025-05-01 21:34 UTC (permalink / raw) To: git To unify mark-up used in our documentation to a newer convention, started by 22293895 (doc: apply synopsis simplification on git-clone and git-init, 2024-09-24), update the documentation of 'git daemon' to * use [synopsis], not [verse] in the SYNOPSIS section * enclose `--option=<value>` in backquotes Also, split '--[no-]option' into '--option' and '--no-option' to make it easier to grep for them. Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/git-daemon.adoc | 107 +++++++++++++++++----------------- 1 file changed, 54 insertions(+), 53 deletions(-) diff --git a/Documentation/git-daemon.adoc b/Documentation/git-daemon.adoc index ede7b935d6..3eb9332e55 100644 --- a/Documentation/git-daemon.adoc +++ b/Documentation/git-daemon.adoc @@ -7,21 +7,21 @@ git-daemon - A really simple server for Git repositories SYNOPSIS -------- -[verse] -'git daemon' [--verbose] [--syslog] [--export-all] - [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>] - [--strict-paths] [--base-path=<path>] [--base-path-relaxed] - [--user-path | --user-path=<path>] - [--interpolated-path=<pathtemplate>] - [--reuseaddr] [--detach] [--pid-file=<file>] - [--enable=<service>] [--disable=<service>] - [--allow-override=<service>] [--forbid-override=<service>] - [--access-hook=<path>] [--[no-]informative-errors] - [--inetd | - [--listen=<host-or-ipaddr>] [--port=<n>] - [--user=<user> [--group=<group>]]] - [--log-destination=(stderr|syslog|none)] - [<directory>...] +[synopsis] +git daemon [--verbose] [--syslog] [--export-all] + [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>] + [--strict-paths] [--base-path=<path>] [--base-path-relaxed] + [--user-path | --user-path=<path>] + [--interpolated-path=<pathtemplate>] + [--reuseaddr] [--detach] [--pid-file=<file>] + [--enable=<service>] [--disable=<service>] + [--allow-override=<service>] [--forbid-override=<service>] + [--access-hook=<path>] [--[no-]informative-errors] + [--inetd | + [--listen=<host-or-ipaddr>] [--port=<n>] + [--user=<user> [--group=<group>]]] + [--log-destination=(stderr|syslog|none)] + [<directory>...] DESCRIPTION ----------- @@ -46,26 +46,26 @@ An `upload-archive` also exists to serve 'git archive'. OPTIONS ------- ---strict-paths:: +`--strict-paths`:: Match paths exactly (i.e. don't allow "/foo/repo" when the real path is "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths. 'git daemon' will refuse to start when this option is enabled and no directory arguments are provided. ---base-path=<path>:: +`--base-path=<path>`:: Remap all the path requests as relative to the given path. This is sort of "Git root" - if you run 'git daemon' with '--base-path=/srv/git' on example.com, then if you later try to pull 'git://example.com/hello.git', 'git daemon' will interpret the path as `/srv/git/hello.git`. ---base-path-relaxed:: - If --base-path is enabled and repo lookup fails, with this option +`--base-path-relaxed`:: + If `--base-path` is enabled and repo lookup fails, with this option 'git daemon' will attempt to lookup without prefixing the base path. - This is useful for switching to --base-path usage, while still + This is useful for switching to `--base-path` usage, while still allowing the old paths. ---interpolated-path=<pathtemplate>:: +`--interpolated-path=<pathtemplate>`:: To support virtual hosting, an interpolated path template can be used to dynamically construct alternate paths. The template supports %H for the target hostname as supplied by the client but @@ -75,48 +75,48 @@ OPTIONS After interpolation, the path is validated against the directory list. ---export-all:: +`--export-all`:: Allow pulling from all directories that look like Git repositories (have the 'objects' and 'refs' subdirectories), even if they do not have the 'git-daemon-export-ok' file. ---inetd:: - Have the server run as an inetd service. Implies --syslog (may be - overridden with `--log-destination=`). - Incompatible with --detach, --port, --listen, --user and --group - options. +`--inetd`:: + Have the server run as an inetd service. Implies `--syslog` (may + be overridden with `--log-destination=`). + Incompatible with `--detach`, `--port`, `--listen`, `--user` and + `--group` options. ---listen=<host-or-ipaddr>:: +`--listen=<host-or-ipaddr>`:: Listen on a specific IP address or hostname. IP addresses can be either an IPv4 address or an IPv6 address if supported. If IPv6 - is not supported, then --listen=<hostname> is also not supported and - --listen must be given an IPv4 address. + is not supported, then `--listen=<hostname>` is also not supported + and `--listen` must be given an IPv4 address. Can be given more than once. Incompatible with `--inetd` option. ---port=<n>:: +`--port=<n>`:: Listen on an alternative port. Incompatible with `--inetd` option. ---init-timeout=<n>:: +`--init-timeout=<n>`:: Timeout (in seconds) between the moment the connection is established and the client request is received (typically a rather low value, since that should be basically immediate). ---timeout=<n>:: +`--timeout=<n>`:: Timeout (in seconds) for specific client sub-requests. This includes the time it takes for the server to process the sub-request and the time spent waiting for the next client's request. ---max-connections=<n>:: +`--max-connections=<n>`:: Maximum number of concurrent clients, defaults to 32. Set it to zero for no limit. ---syslog:: +`--syslog`:: Short for `--log-destination=syslog`. ---log-destination=<destination>:: +`--log-destination=<destination>`:: Send log messages to the specified destination. - Note that this option does not imply --verbose, + Note that this option does not imply `--verbose`, thus by default only error conditions will be logged. The <destination> must be one of: + @@ -135,8 +135,8 @@ none:: The default destination is `syslog` if `--inetd` or `--detach` is specified, otherwise `stderr`. ---user-path:: ---user-path=<path>:: +`--user-path`:: +`--user-path=<path>`:: Allow {tilde}user notation to be used in requests. When specified with no parameter, a request to git://host/{tilde}alice/foo is taken as a request to access @@ -145,23 +145,23 @@ otherwise `stderr`. taken as a request to access `<path>/foo` repository in the home directory of user `alice`. ---verbose:: +`--verbose`:: Log details about the incoming connections and requested files. ---reuseaddr:: +`--reuseaddr`:: Use SO_REUSEADDR when binding the listening socket. This allows the server to restart without waiting for old connections to time out. ---detach:: - Detach from the shell. Implies --syslog. +`--detach`:: + Detach from the shell. Implies `--syslog`. ---pid-file=<file>:: +`--pid-file=<file>`:: Save the process id in 'file'. Ignored when the daemon is run under `--inetd`. ---user=<user>:: ---group=<group>:: +`--user=<user>`:: +`--group=<group>`:: Change daemon's uid and gid before entering the service loop. When only `--user` is given without `--group`, the primary group ID for the user is used. The values of @@ -179,30 +179,31 @@ may also want to set and export `HOME` to point at the home directory of `<user>` before starting the daemon, and make sure any Git configuration files in that directory are readable by `<user>`. ---enable=<service>:: ---disable=<service>:: +`--enable=<service>`:: +`--disable=<service>`:: Enable/disable the service site-wide per default. Note that a service disabled site-wide can still be enabled per repository if it is marked overridable and the repository enables the service with a configuration item. ---allow-override=<service>:: ---forbid-override=<service>:: +`--allow-override=<service>`:: +`--forbid-override=<service>`:: Allow/forbid overriding the site-wide default with per repository configuration. By default, all the services may be overridden. ---[no-]informative-errors:: +`--informative-errors`:: +`--no-informative-errors`:: When informative errors are turned on, git-daemon will report more verbose errors to the client, differentiating conditions like "no such repository" from "repository not exported". This is more convenient for clients, but may leak information about the existence of unexported repositories. When informative errors are not enabled, all errors report "access denied" to the - client. The default is --no-informative-errors. + client. The default is `--no-informative-errors`. ---access-hook=<path>:: +`--access-hook=<path>`:: Every time a client connects, first run an external command specified by the <path> with service name (e.g. "upload-pack"), path to the repository, hostname (%H), canonical hostname -- 2.49.0-599-g90c2cffacf ^ permalink raw reply related [flat|nested] 26+ messages in thread
* Re: [PATCH 3/4] git-daemon doc: update mark-up of synopsis option descriptions 2025-05-01 21:34 ` [PATCH 3/4] git-daemon doc: " Junio C Hamano @ 2025-05-01 22:52 ` Eric Sunshine 2025-05-01 23:12 ` Junio C Hamano 0 siblings, 1 reply; 26+ messages in thread From: Eric Sunshine @ 2025-05-01 22:52 UTC (permalink / raw) To: Junio C Hamano; +Cc: git On Thu, May 1, 2025 at 5:34 PM Junio C Hamano <gitster@pobox.com> wrote: > To unify mark-up used in our documentation to a newer convention, > started by 22293895 (doc: apply synopsis simplification on git-clone > and git-init, 2024-09-24), update the documentation of 'git daemon' > to > > * use [synopsis], not [verse] in the SYNOPSIS section > * enclose `--option=<value>` in backquotes > > Also, split '--[no-]option' into '--option' and '--no-option' > to make it easier to grep for them. > > Signed-off-by: Junio C Hamano <gitster@pobox.com> > --- > diff --git a/Documentation/git-daemon.adoc b/Documentation/git-daemon.adoc > @@ -46,26 +46,26 @@ An `upload-archive` also exists to serve 'git archive'. > ---strict-paths:: > +`--strict-paths`:: > Match paths exactly (i.e. don't allow "/foo/repo" when the real path is > "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths. > 'git daemon' will refuse to start when this option is enabled and no > directory arguments are provided. Should 'git daemon' be wrapped in backticks instead? > ---base-path=<path>:: > +`--base-path=<path>`:: > Remap all the path requests as relative to the given path. > This is sort of "Git root" - if you run 'git daemon' with > '--base-path=/srv/git' on example.com, then if you later try to pull Should the '--base-path=/srv/git' example be wrapped in backticks instead? > 'git://example.com/hello.git', 'git daemon' will interpret the path > as `/srv/git/hello.git`. These are inconsistent, as well: the first two use apostrophes, and the latter backticks. > @@ -135,8 +135,8 @@ none:: > +`--user-path`:: > +`--user-path=<path>`:: > Allow {tilde}user notation to be used in requests. When > specified with no parameter, a request to > git://host/{tilde}alice/foo is taken as a request to access And this URL has no quoting. ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH 3/4] git-daemon doc: update mark-up of synopsis option descriptions 2025-05-01 22:52 ` Eric Sunshine @ 2025-05-01 23:12 ` Junio C Hamano 2025-05-01 23:22 ` Junio C Hamano 0 siblings, 1 reply; 26+ messages in thread From: Junio C Hamano @ 2025-05-01 23:12 UTC (permalink / raw) To: Eric Sunshine; +Cc: git Eric Sunshine <sunshine@sunshineco.com> writes: >> diff --git a/Documentation/git-daemon.adoc b/Documentation/git-daemon.adoc >> @@ -46,26 +46,26 @@ An `upload-archive` also exists to serve 'git archive'. >> ---strict-paths:: >> +`--strict-paths`:: >> Match paths exactly (i.e. don't allow "/foo/repo" when the real path is >> "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths. >> 'git daemon' will refuse to start when this option is enabled and no >> directory arguments are provided. > > Should 'git daemon' be wrapped in backticks instead? Yup, good eyes. >> ---base-path=<path>:: >> +`--base-path=<path>`:: >> Remap all the path requests as relative to the given path. >> This is sort of "Git root" - if you run 'git daemon' with >> '--base-path=/srv/git' on example.com, then if you later try to pull > > Should the '--base-path=/srv/git' example be wrapped in backticks instead? Probably, so should `git daemon` one line before it. >> 'git://example.com/hello.git', 'git daemon' will interpret the path >> as `/srv/git/hello.git`. > > These are inconsistent, as well: the first two use apostrophes, and > the latter backticks. I am not sure what the best mark-up for the sample strings. They are not what the end-users are expected to type verbatim, so I've punted and left them out as in the original ;-) >> @@ -135,8 +135,8 @@ none:: >> +`--user-path`:: >> +`--user-path=<path>`:: >> Allow {tilde}user notation to be used in requests. When >> specified with no parameter, a request to >> git://host/{tilde}alice/foo is taken as a request to access > > And this URL has no quoting. Likewise. ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH 3/4] git-daemon doc: update mark-up of synopsis option descriptions 2025-05-01 23:12 ` Junio C Hamano @ 2025-05-01 23:22 ` Junio C Hamano 0 siblings, 0 replies; 26+ messages in thread From: Junio C Hamano @ 2025-05-01 23:22 UTC (permalink / raw) To: Eric Sunshine; +Cc: git, Jean-Noël Avila Here are incremental changes relative to the previous round, taking inspiration from your suggestions. I think the sample option, sitename, and pathname must be typed verbatim by the readers if the behaviour described in the text is to be reproduced, so changed them in the base-path description all to be marked up as `literal string`. diff --git c/Documentation/git-daemon.adoc w/Documentation/git-daemon.adoc index 3eb9332e55..bc3f77405e 100644 --- c/Documentation/git-daemon.adoc +++ w/Documentation/git-daemon.adoc @@ -32,7 +32,7 @@ that service if it is enabled. It verifies that the directory has the magic file "git-daemon-export-ok", and it will refuse to export any Git directory that hasn't explicitly been marked for export this way (unless the `--export-all` parameter is specified). If you -pass some directory paths as 'git daemon' arguments, the offers are limited to +pass some directory paths as `git daemon` arguments, the offers are limited to repositories within those directories. By default, only `upload-pack` service is enabled, which serves @@ -49,15 +49,15 @@ OPTIONS `--strict-paths`:: Match paths exactly (i.e. don't allow "/foo/repo" when the real path is "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths. - 'git daemon' will refuse to start when this option is enabled and no + `git daemon` will refuse to start when this option is enabled and no directory arguments are provided. `--base-path=<path>`:: Remap all the path requests as relative to the given path. - This is sort of "Git root" - if you run 'git daemon' with - '--base-path=/srv/git' on example.com, then if you later try to pull - 'git://example.com/hello.git', 'git daemon' will interpret the path - as `/srv/git/hello.git`. + This is sort of "Git root" - if you run `git daemon` with + `--base-path=/srv/git` on `example.com`, then if you later try + to pull from `git://example.com/hello.git`, `git daemon` will + interpret the path as `/srv/git/hello.git`. `--base-path-relaxed`:: If `--base-path` is enabled and repo lookup fails, with this option ^ permalink raw reply related [flat|nested] 26+ messages in thread
* [WIP PATCH 4/4] git-worktree doc: update mark-up of synopsis option descriptions 2025-05-01 21:34 [PATCH 0/4] A handful of doc synopsis/options update Junio C Hamano ` (2 preceding siblings ...) 2025-05-01 21:34 ` [PATCH 3/4] git-daemon doc: " Junio C Hamano @ 2025-05-01 21:34 ` Junio C Hamano 2025-05-03 1:15 ` [PATCH v2 0/3] A handful of doc synopsis/options update Junio C Hamano 2025-05-10 12:33 ` [PATCH v3 0/4] " Jean-Noël Avila 5 siblings, 0 replies; 26+ messages in thread From: Junio C Hamano @ 2025-05-01 21:34 UTC (permalink / raw) To: git To unify mark-up used in our documentation to a newer convention, started by 22293895 (doc: apply synopsis simplification on git-clone and git-init, 2024-09-24), update the documentation of 'git worktree' to * use [synopsis], not [verse] in the SYNOPSIS section * enclose `--option=<value>` in backquotes Also, split '--[no-]option' into '--option' and '--no-option' to make it easier to grep for them. Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/git-worktree.adoc | 71 ++++++++++++++++++--------------- 1 file changed, 38 insertions(+), 33 deletions(-) diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc index 8340b7f028..46715cbef7 100644 --- a/Documentation/git-worktree.adoc +++ b/Documentation/git-worktree.adoc @@ -8,16 +8,16 @@ git-worktree - Manage multiple working trees SYNOPSIS -------- -[verse] -'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] - [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>] -'git worktree list' [-v | --porcelain [-z]] -'git worktree lock' [--reason <string>] <worktree> -'git worktree move' <worktree> <new-path> -'git worktree prune' [-n] [-v] [--expire <expire>] -'git worktree remove' [-f] <worktree> -'git worktree repair' [<path>...] -'git worktree unlock' <worktree> +[synopsis] +git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]] + [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>] +git worktree list [-v | --porcelain [-z]] +git worktree lock [--reason <string>] <worktree> +git worktree move <worktree> <new-path> +git worktree prune [-n] [-v] [--expire <expire>] +git worktree remove [-f] <worktree> +git worktree repair [<path>...] +git worktree unlock <worktree> DESCRIPTION ----------- @@ -169,8 +169,8 @@ Unlock a worktree, allowing it to be pruned, moved or deleted. OPTIONS ------- --f:: ---force:: +`-f`:: +`--force`:: By default, `add` refuses to create a new worktree when `<commit-ish>` is a branch name and is already checked out by another worktree, or if `<path>` is already assigned to some @@ -186,8 +186,8 @@ allows the move to proceed; use `--force` twice if the destination is locked. `remove` refuses to remove an unclean worktree unless `--force` is used. To remove a locked worktree, specify `--force` twice. --b <new-branch>:: --B <new-branch>:: +`-b <new-branch>`:: +`-B <new-branch>`:: With `add`, create a new branch named `<new-branch>` starting at `<commit-ish>`, and check out `<new-branch>` into the new worktree. If `<commit-ish>` is omitted, it defaults to `HEAD`. @@ -195,18 +195,20 @@ To remove a locked worktree, specify `--force` twice. exists. `-B` overrides this safeguard, resetting `<new-branch>` to `<commit-ish>`. --d:: ---detach:: +`-d`:: +`--detach`:: With `add`, detach `HEAD` in the new worktree. See "DETACHED HEAD" in linkgit:git-checkout[1]. ---[no-]checkout:: +`--checkout`:: +`--no-checkout`:: By default, `add` checks out `<commit-ish>`, however, `--no-checkout` can be used to suppress checkout in order to make customizations, such as configuring sparse-checkout. See "Sparse checkout" in linkgit:git-read-tree[1]. ---[no-]guess-remote:: +`--guess-remote`:: +`--no-guess-remote`:: With `worktree add <path>`, without `<commit-ish>`, instead of creating a new branch from `HEAD`, if there exists a tracking branch in exactly one remote matching the basename of `<path>`, @@ -216,7 +218,8 @@ To remove a locked worktree, specify `--force` twice. This can also be set up as the default behaviour by using the `worktree.guessRemote` config option. ---[no-]relative-paths:: +`--relative-paths` +`--no-relative-paths`:: Link worktrees using relative paths or absolute paths (default). Overrides the `worktree.useRelativePaths` config option, see linkgit:git-config[1]. @@ -224,55 +227,57 @@ This can also be set up as the default behaviour by using the With `repair`, the linking files will be updated if there's an absolute/relative mismatch, even if the links are correct. ---[no-]track:: - When creating a new branch, if `<commit-ish>` is a branch, +`--track`:: +`--no-track`:: + With `--track`, when creating a new branch, + if `<commit-ish>` is a branch, mark it as "upstream" from the new branch. This is the default if `<commit-ish>` is a remote-tracking branch. See `--track` in linkgit:git-branch[1] for details. ---lock:: +`--lock`:: Keep the worktree locked after creation. This is the equivalent of `git worktree lock` after `git worktree add`, but without a race condition. --n:: ---dry-run:: +`-n`:: +`--dry-run`:: With `prune`, do not remove anything; just report what it would remove. ---orphan:: +`--orphan`:: With `add`, make the new worktree and index empty, associating the worktree with a new unborn branch named `<new-branch>`. ---porcelain:: +`--porcelain`:: With `list`, output in an easy-to-parse format for scripts. This format will remain stable across Git versions and regardless of user configuration. It is recommended to combine this with `-z`. See below for details. --z:: +`-z`:: Terminate each line with a NUL rather than a newline when `--porcelain` is specified with `list`. This makes it possible to parse the output when a worktree path contains a newline character. --q:: ---quiet:: +`-q`:: +`--quiet`:: With `add`, suppress feedback messages. --v:: ---verbose:: +`-v`:: +`--verbose`:: With `prune`, report all removals. + With `list`, output additional information about worktrees (see below). ---expire <time>:: +`--expire <time>`:: With `prune`, only expire unused worktrees older than `<time>`. + With `list`, annotate missing worktrees as prunable if they are older than `<time>`. ---reason <string>:: +`--reason <string>`:: With `lock` or with `add --lock`, an explanation why the worktree is locked. -- 2.49.0-599-g90c2cffacf ^ permalink raw reply related [flat|nested] 26+ messages in thread
* [PATCH v2 0/3] A handful of doc synopsis/options update 2025-05-01 21:34 [PATCH 0/4] A handful of doc synopsis/options update Junio C Hamano ` (3 preceding siblings ...) 2025-05-01 21:34 ` [WIP PATCH 4/4] git-worktree " Junio C Hamano @ 2025-05-03 1:15 ` Junio C Hamano 2025-05-03 1:15 ` [PATCH v2 1/3] git-verify-* doc: update mark-up of synopsis option descriptions Junio C Hamano ` (3 more replies) 2025-05-10 12:33 ` [PATCH v3 0/4] " Jean-Noël Avila 5 siblings, 4 replies; 26+ messages in thread From: Junio C Hamano @ 2025-05-03 1:15 UTC (permalink / raw) To: git Continuing what Jean-Noël started with 22293895 (doc: apply synopsis simplification on git-clone and git-init, 2024-09-24), use more [synopsis] (rather than [verse]) mark-up and also make sure - dashed options in the text, including the heading for enumerated dashed options in the OPTIONS section, are `backquoted` to be typeset verbatim. - both positive and negative variants are spelled out when the option is negatable, i.e. a heading "--[no-]opt::" is separated into "--opt::" and "--no-opt::", to help grep hit with simpler patterns. - non-options are not described in the OPTIONS section. The changes in the first two patches are unchanged. The update to "git daemon" documentation has acquired a bit more `literal` mark-ups, prompted by a comment by Eric Sunshine on the previous iteration. The initial iteration contained a WIP on worktree documentation, which has been dropped in this iteration. 1: 65a5556d4b = 1: 5e8ae75a6b git-verify-* doc: update mark-up of synopsis option descriptions 2: a9c5bd63ee = 2: c6cc44c72b git-{var,write-tree} docs: update mark-up of synopsis option descriptions 3: eb0e783e21 ! 3: d424d8c846 git-daemon doc: update mark-up of synopsis option descriptions @@ Documentation/git-daemon.adoc: git-daemon - A really simple server for Git repos DESCRIPTION ----------- +@@ Documentation/git-daemon.adoc: that service if it is enabled. + It verifies that the directory has the magic file "git-daemon-export-ok", and + it will refuse to export any Git directory that hasn't explicitly been marked + for export this way (unless the `--export-all` parameter is specified). If you +-pass some directory paths as 'git daemon' arguments, the offers are limited to ++pass some directory paths as `git daemon` arguments, the offers are limited to + repositories within those directories. + + By default, only `upload-pack` service is enabled, which serves @@ Documentation/git-daemon.adoc: An `upload-archive` also exists to serve 'git archive'. OPTIONS @@ Documentation/git-daemon.adoc: An `upload-archive` also exists to serve 'git arc +`--strict-paths`:: Match paths exactly (i.e. don't allow "/foo/repo" when the real path is "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths. - 'git daemon' will refuse to start when this option is enabled and no +- 'git daemon' will refuse to start when this option is enabled and no ++ `git daemon` will refuse to start when this option is enabled and no directory arguments are provided. ---base-path=<path>:: +`--base-path=<path>`:: Remap all the path requests as relative to the given path. - This is sort of "Git root" - if you run 'git daemon' with - '--base-path=/srv/git' on example.com, then if you later try to pull - 'git://example.com/hello.git', 'git daemon' will interpret the path - as `/srv/git/hello.git`. +- This is sort of "Git root" - if you run 'git daemon' with +- '--base-path=/srv/git' on example.com, then if you later try to pull +- 'git://example.com/hello.git', 'git daemon' will interpret the path +- as `/srv/git/hello.git`. ++ This is sort of "Git root" - if you run `git daemon` with ++ `--base-path=/srv/git` on `example.com`, then if you later try ++ to pull from `git://example.com/hello.git`, `git daemon` will ++ interpret the path as `/srv/git/hello.git`. ---base-path-relaxed:: - If --base-path is enabled and repo lookup fails, with this option Junio C Hamano (3): git-verify-* doc: update mark-up of synopsis option descriptions git-{var,write-tree} docs: update mark-up of synopsis option descriptions git-daemon doc: update mark-up of synopsis option descriptions Documentation/git-daemon.adoc | 119 ++++++++++++++------------- Documentation/git-var.adoc | 6 +- Documentation/git-verify-commit.adoc | 16 ++-- Documentation/git-verify-pack.adoc | 28 +++---- Documentation/git-verify-tag.adoc | 16 ++-- Documentation/git-write-tree.adoc | 16 ++-- 6 files changed, 97 insertions(+), 104 deletions(-) -- 2.49.0-601-ga5925c3955 ^ permalink raw reply [flat|nested] 26+ messages in thread
* [PATCH v2 1/3] git-verify-* doc: update mark-up of synopsis option descriptions 2025-05-03 1:15 ` [PATCH v2 0/3] A handful of doc synopsis/options update Junio C Hamano @ 2025-05-03 1:15 ` Junio C Hamano 2025-05-03 1:15 ` [PATCH v2 2/3] git-{var,write-tree} docs: " Junio C Hamano ` (2 subsequent siblings) 3 siblings, 0 replies; 26+ messages in thread From: Junio C Hamano @ 2025-05-03 1:15 UTC (permalink / raw) To: git To unify mark-up used in our documentation to a newer convention, started by 22293895 (doc: apply synopsis simplification on git-clone and git-init, 2024-09-24), update the documentation pages for 'git verify-commit', 'git verify-tag', and 'git verify-pack' to * use [synopsis], not [verse] in the SYNOPSIS section * enclose `--option=<value>` in backquotes * do not describe non-option arguments in the OPTIONS section Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/git-verify-commit.adoc | 16 +++++++--------- Documentation/git-verify-pack.adoc | 28 ++++++++++++---------------- Documentation/git-verify-tag.adoc | 16 +++++++--------- 3 files changed, 26 insertions(+), 34 deletions(-) diff --git a/Documentation/git-verify-commit.adoc b/Documentation/git-verify-commit.adoc index aee4c40eac..ff5b8b97ef 100644 --- a/Documentation/git-verify-commit.adoc +++ b/Documentation/git-verify-commit.adoc @@ -7,26 +7,24 @@ git-verify-commit - Check the GPG signature of commits SYNOPSIS -------- -[verse] -'git verify-commit' [-v | --verbose] [--raw] <commit>... +[synopsis] +git verify-commit [-v | --verbose] [--raw] <commit>... DESCRIPTION ----------- -Validates the GPG signature created by 'git commit -S'. +Validates the GPG signature created by `git commit -S` +on the commit objects given on the command line. OPTIONS ------- ---raw:: +`--raw`:: Print the raw gpg status output to standard error instead of the normal human-readable output. --v:: ---verbose:: +`-v`:: +`--verbose`:: Print the contents of the commit object before validating it. -<commit>...:: - SHA-1 identifiers of Git commit objects. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-verify-pack.adoc b/Documentation/git-verify-pack.adoc index d7e886918a..b0462d8db3 100644 --- a/Documentation/git-verify-pack.adoc +++ b/Documentation/git-verify-pack.adoc @@ -8,43 +8,39 @@ git-verify-pack - Validate packed Git archive files SYNOPSIS -------- -[verse] -'git verify-pack' [-v | --verbose] [-s | --stat-only] [--] <pack>.idx... +[synopsis] +git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx... DESCRIPTION ----------- -Reads given idx file for packed Git archive created with the -'git pack-objects' command and verifies the idx file and the -corresponding pack file. +Read each idx file for packed Git archive given on the command line, +and verify the idx file and the corresponding pack file. OPTIONS ------- -<pack>.idx ...:: - The idx files to verify. - --v:: ---verbose:: +`-v`:: +`--verbose`:: After verifying the pack, show the list of objects contained in the pack and a histogram of delta chain length. --s:: ---stat-only:: +`-s`:: +`--stat-only`:: Do not verify the pack contents; only show the histogram of delta chain length. With `--verbose`, the list of objects is also shown. -\--:: +`--`:: Do not interpret any more arguments as options. OUTPUT FORMAT ------------- -When specifying the -v option the format used is: +When specifying the `-v` option the format used is: - SHA-1 type size size-in-packfile offset-in-packfile + object-name type size size-in-packfile offset-in-packfile for objects that are not deltified in the pack, and - SHA-1 type size size-in-packfile offset-in-packfile depth base-SHA-1 + object-name type size size-in-packfile offset-in-packfile depth base-object-name for objects that are deltified. diff --git a/Documentation/git-verify-tag.adoc b/Documentation/git-verify-tag.adoc index 81d50ecc4c..ec995323f6 100644 --- a/Documentation/git-verify-tag.adoc +++ b/Documentation/git-verify-tag.adoc @@ -7,26 +7,24 @@ git-verify-tag - Check the GPG signature of tags SYNOPSIS -------- -[verse] -'git verify-tag' [-v | --verbose] [--format=<format>] [--raw] <tag>... +[synopsis] +git verify-tag [-v | --verbose] [--format=<format>] [--raw] <tag>... DESCRIPTION ----------- -Validates the gpg signature created by 'git tag'. +Validates the gpg signature created by 'git tag' in the tag +objects listed on the command line. OPTIONS ------- ---raw:: +`--raw`:: Print the raw gpg status output to standard error instead of the normal human-readable output. --v:: ---verbose:: +`-v`:: +`--verbose`:: Print the contents of the tag object before validating it. -<tag>...:: - SHA-1 identifiers of Git tag objects. - GIT --- Part of the linkgit:git[1] suite -- 2.49.0-601-ga5925c3955 ^ permalink raw reply related [flat|nested] 26+ messages in thread
* [PATCH v2 2/3] git-{var,write-tree} docs: update mark-up of synopsis option descriptions 2025-05-03 1:15 ` [PATCH v2 0/3] A handful of doc synopsis/options update Junio C Hamano 2025-05-03 1:15 ` [PATCH v2 1/3] git-verify-* doc: update mark-up of synopsis option descriptions Junio C Hamano @ 2025-05-03 1:15 ` Junio C Hamano 2025-05-03 1:15 ` [PATCH v2 3/3] git-daemon doc: " Junio C Hamano 2025-05-07 20:58 ` Additional changes Jean-Noël Avila 3 siblings, 0 replies; 26+ messages in thread From: Junio C Hamano @ 2025-05-03 1:15 UTC (permalink / raw) To: git To unify mark-up used in our documentation to a newer convention, started by 22293895 (doc: apply synopsis simplification on git-clone and git-init, 2024-09-24), update the documentation for 'git var' and 'git write-tree' to * use [synopsis], not [verse] in the SYNOPSIS section * enclose `--option=<value>` in backquotes Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/git-var.adoc | 6 +++--- Documentation/git-write-tree.adoc | 16 ++++++++-------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/Documentation/git-var.adoc b/Documentation/git-var.adoc index 0680568dfd..909963b1c2 100644 --- a/Documentation/git-var.adoc +++ b/Documentation/git-var.adoc @@ -8,8 +8,8 @@ git-var - Show a Git logical variable SYNOPSIS -------- -[verse] -'git var' (-l | <variable>) +[synopsis] +git var (-l | <variable>) DESCRIPTION ----------- @@ -18,7 +18,7 @@ no value. OPTIONS ------- --l:: +`-l`:: Display the logical variables. In addition, all the variables of the Git configuration file .git/config are listed as well. (However, the configuration variables listing functionality diff --git a/Documentation/git-write-tree.adoc b/Documentation/git-write-tree.adoc index f22041a9dc..4e1c3b9c0c 100644 --- a/Documentation/git-write-tree.adoc +++ b/Documentation/git-write-tree.adoc @@ -8,8 +8,8 @@ git-write-tree - Create a tree object from the current index SYNOPSIS -------- -[verse] -'git write-tree' [--missing-ok] [--prefix=<prefix>/] +[synopsis] +git write-tree [--missing-ok] [--prefix=<prefix>/] DESCRIPTION ----------- @@ -18,21 +18,21 @@ tree object is printed to standard output. The index must be in a fully merged state. -Conceptually, 'git write-tree' sync()s the current index contents +Conceptually, `git write-tree` sync()s the current index contents into a set of tree files. In order to have that match what is actually in your directory right -now, you need to have done a 'git update-index' phase before you did the -'git write-tree'. +now, you need to have done a `git update-index` phase before you did the +`git write-tree`. OPTIONS ------- ---missing-ok:: - Normally 'git write-tree' ensures that the objects referenced by the +`--missing-ok`:: + Normally `git write-tree` ensures that the objects referenced by the directory exist in the object database. This option disables this check. ---prefix=<prefix>/:: +`--prefix=<prefix>/`:: Writes a tree object that represents a subdirectory `<prefix>`. This can be used to write the tree object for a subproject that is in the named subdirectory. -- 2.49.0-601-ga5925c3955 ^ permalink raw reply related [flat|nested] 26+ messages in thread
* [PATCH v2 3/3] git-daemon doc: update mark-up of synopsis option descriptions 2025-05-03 1:15 ` [PATCH v2 0/3] A handful of doc synopsis/options update Junio C Hamano 2025-05-03 1:15 ` [PATCH v2 1/3] git-verify-* doc: update mark-up of synopsis option descriptions Junio C Hamano 2025-05-03 1:15 ` [PATCH v2 2/3] git-{var,write-tree} docs: " Junio C Hamano @ 2025-05-03 1:15 ` Junio C Hamano 2025-05-07 20:58 ` Additional changes Jean-Noël Avila 3 siblings, 0 replies; 26+ messages in thread From: Junio C Hamano @ 2025-05-03 1:15 UTC (permalink / raw) To: git To unify mark-up used in our documentation to a newer convention, started by 22293895 (doc: apply synopsis simplification on git-clone and git-init, 2024-09-24), update the documentation of 'git daemon' to * use [synopsis], not [verse] in the SYNOPSIS section * enclose `--option=<value>` in backquotes Also, split '--[no-]option' into '--option' and '--no-option' to make it easier to grep for them. Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/git-daemon.adoc | 119 +++++++++++++++++----------------- 1 file changed, 60 insertions(+), 59 deletions(-) diff --git a/Documentation/git-daemon.adoc b/Documentation/git-daemon.adoc index ede7b935d6..bc3f77405e 100644 --- a/Documentation/git-daemon.adoc +++ b/Documentation/git-daemon.adoc @@ -7,21 +7,21 @@ git-daemon - A really simple server for Git repositories SYNOPSIS -------- -[verse] -'git daemon' [--verbose] [--syslog] [--export-all] - [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>] - [--strict-paths] [--base-path=<path>] [--base-path-relaxed] - [--user-path | --user-path=<path>] - [--interpolated-path=<pathtemplate>] - [--reuseaddr] [--detach] [--pid-file=<file>] - [--enable=<service>] [--disable=<service>] - [--allow-override=<service>] [--forbid-override=<service>] - [--access-hook=<path>] [--[no-]informative-errors] - [--inetd | - [--listen=<host-or-ipaddr>] [--port=<n>] - [--user=<user> [--group=<group>]]] - [--log-destination=(stderr|syslog|none)] - [<directory>...] +[synopsis] +git daemon [--verbose] [--syslog] [--export-all] + [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>] + [--strict-paths] [--base-path=<path>] [--base-path-relaxed] + [--user-path | --user-path=<path>] + [--interpolated-path=<pathtemplate>] + [--reuseaddr] [--detach] [--pid-file=<file>] + [--enable=<service>] [--disable=<service>] + [--allow-override=<service>] [--forbid-override=<service>] + [--access-hook=<path>] [--[no-]informative-errors] + [--inetd | + [--listen=<host-or-ipaddr>] [--port=<n>] + [--user=<user> [--group=<group>]]] + [--log-destination=(stderr|syslog|none)] + [<directory>...] DESCRIPTION ----------- @@ -32,7 +32,7 @@ that service if it is enabled. It verifies that the directory has the magic file "git-daemon-export-ok", and it will refuse to export any Git directory that hasn't explicitly been marked for export this way (unless the `--export-all` parameter is specified). If you -pass some directory paths as 'git daemon' arguments, the offers are limited to +pass some directory paths as `git daemon` arguments, the offers are limited to repositories within those directories. By default, only `upload-pack` service is enabled, which serves @@ -46,26 +46,26 @@ An `upload-archive` also exists to serve 'git archive'. OPTIONS ------- ---strict-paths:: +`--strict-paths`:: Match paths exactly (i.e. don't allow "/foo/repo" when the real path is "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths. - 'git daemon' will refuse to start when this option is enabled and no + `git daemon` will refuse to start when this option is enabled and no directory arguments are provided. ---base-path=<path>:: +`--base-path=<path>`:: Remap all the path requests as relative to the given path. - This is sort of "Git root" - if you run 'git daemon' with - '--base-path=/srv/git' on example.com, then if you later try to pull - 'git://example.com/hello.git', 'git daemon' will interpret the path - as `/srv/git/hello.git`. + This is sort of "Git root" - if you run `git daemon` with + `--base-path=/srv/git` on `example.com`, then if you later try + to pull from `git://example.com/hello.git`, `git daemon` will + interpret the path as `/srv/git/hello.git`. ---base-path-relaxed:: - If --base-path is enabled and repo lookup fails, with this option +`--base-path-relaxed`:: + If `--base-path` is enabled and repo lookup fails, with this option 'git daemon' will attempt to lookup without prefixing the base path. - This is useful for switching to --base-path usage, while still + This is useful for switching to `--base-path` usage, while still allowing the old paths. ---interpolated-path=<pathtemplate>:: +`--interpolated-path=<pathtemplate>`:: To support virtual hosting, an interpolated path template can be used to dynamically construct alternate paths. The template supports %H for the target hostname as supplied by the client but @@ -75,48 +75,48 @@ OPTIONS After interpolation, the path is validated against the directory list. ---export-all:: +`--export-all`:: Allow pulling from all directories that look like Git repositories (have the 'objects' and 'refs' subdirectories), even if they do not have the 'git-daemon-export-ok' file. ---inetd:: - Have the server run as an inetd service. Implies --syslog (may be - overridden with `--log-destination=`). - Incompatible with --detach, --port, --listen, --user and --group - options. +`--inetd`:: + Have the server run as an inetd service. Implies `--syslog` (may + be overridden with `--log-destination=`). + Incompatible with `--detach`, `--port`, `--listen`, `--user` and + `--group` options. ---listen=<host-or-ipaddr>:: +`--listen=<host-or-ipaddr>`:: Listen on a specific IP address or hostname. IP addresses can be either an IPv4 address or an IPv6 address if supported. If IPv6 - is not supported, then --listen=<hostname> is also not supported and - --listen must be given an IPv4 address. + is not supported, then `--listen=<hostname>` is also not supported + and `--listen` must be given an IPv4 address. Can be given more than once. Incompatible with `--inetd` option. ---port=<n>:: +`--port=<n>`:: Listen on an alternative port. Incompatible with `--inetd` option. ---init-timeout=<n>:: +`--init-timeout=<n>`:: Timeout (in seconds) between the moment the connection is established and the client request is received (typically a rather low value, since that should be basically immediate). ---timeout=<n>:: +`--timeout=<n>`:: Timeout (in seconds) for specific client sub-requests. This includes the time it takes for the server to process the sub-request and the time spent waiting for the next client's request. ---max-connections=<n>:: +`--max-connections=<n>`:: Maximum number of concurrent clients, defaults to 32. Set it to zero for no limit. ---syslog:: +`--syslog`:: Short for `--log-destination=syslog`. ---log-destination=<destination>:: +`--log-destination=<destination>`:: Send log messages to the specified destination. - Note that this option does not imply --verbose, + Note that this option does not imply `--verbose`, thus by default only error conditions will be logged. The <destination> must be one of: + @@ -135,8 +135,8 @@ none:: The default destination is `syslog` if `--inetd` or `--detach` is specified, otherwise `stderr`. ---user-path:: ---user-path=<path>:: +`--user-path`:: +`--user-path=<path>`:: Allow {tilde}user notation to be used in requests. When specified with no parameter, a request to git://host/{tilde}alice/foo is taken as a request to access @@ -145,23 +145,23 @@ otherwise `stderr`. taken as a request to access `<path>/foo` repository in the home directory of user `alice`. ---verbose:: +`--verbose`:: Log details about the incoming connections and requested files. ---reuseaddr:: +`--reuseaddr`:: Use SO_REUSEADDR when binding the listening socket. This allows the server to restart without waiting for old connections to time out. ---detach:: - Detach from the shell. Implies --syslog. +`--detach`:: + Detach from the shell. Implies `--syslog`. ---pid-file=<file>:: +`--pid-file=<file>`:: Save the process id in 'file'. Ignored when the daemon is run under `--inetd`. ---user=<user>:: ---group=<group>:: +`--user=<user>`:: +`--group=<group>`:: Change daemon's uid and gid before entering the service loop. When only `--user` is given without `--group`, the primary group ID for the user is used. The values of @@ -179,30 +179,31 @@ may also want to set and export `HOME` to point at the home directory of `<user>` before starting the daemon, and make sure any Git configuration files in that directory are readable by `<user>`. ---enable=<service>:: ---disable=<service>:: +`--enable=<service>`:: +`--disable=<service>`:: Enable/disable the service site-wide per default. Note that a service disabled site-wide can still be enabled per repository if it is marked overridable and the repository enables the service with a configuration item. ---allow-override=<service>:: ---forbid-override=<service>:: +`--allow-override=<service>`:: +`--forbid-override=<service>`:: Allow/forbid overriding the site-wide default with per repository configuration. By default, all the services may be overridden. ---[no-]informative-errors:: +`--informative-errors`:: +`--no-informative-errors`:: When informative errors are turned on, git-daemon will report more verbose errors to the client, differentiating conditions like "no such repository" from "repository not exported". This is more convenient for clients, but may leak information about the existence of unexported repositories. When informative errors are not enabled, all errors report "access denied" to the - client. The default is --no-informative-errors. + client. The default is `--no-informative-errors`. ---access-hook=<path>:: +`--access-hook=<path>`:: Every time a client connects, first run an external command specified by the <path> with service name (e.g. "upload-pack"), path to the repository, hostname (%H), canonical hostname -- 2.49.0-601-ga5925c3955 ^ permalink raw reply related [flat|nested] 26+ messages in thread
* Additional changes 2025-05-03 1:15 ` [PATCH v2 0/3] A handful of doc synopsis/options update Junio C Hamano ` (2 preceding siblings ...) 2025-05-03 1:15 ` [PATCH v2 3/3] git-daemon doc: " Junio C Hamano @ 2025-05-07 20:58 ` Jean-Noël Avila 2025-05-07 20:58 ` [PATCH] " Jean-Noël Avila 3 siblings, 1 reply; 26+ messages in thread From: Jean-Noël Avila @ 2025-05-07 20:58 UTC (permalink / raw) To: git, Junio C Hamano Thank you for helping out with this dull task. Here are a few additional changes after reviewing the manpages. Thanks Jean-Noël ^ permalink raw reply [flat|nested] 26+ messages in thread
* [PATCH] Additional changes 2025-05-07 20:58 ` Additional changes Jean-Noël Avila @ 2025-05-07 20:58 ` Jean-Noël Avila 2025-05-08 15:14 ` Junio C Hamano 0 siblings, 1 reply; 26+ messages in thread From: Jean-Noël Avila @ 2025-05-07 20:58 UTC (permalink / raw) To: git, Junio C Hamano; +Cc: Jean-Noël Avila --- Documentation/git-daemon.adoc | 60 +++++++++++++++---------------- Documentation/git-var.adoc | 40 ++++++++++----------- Documentation/git-verify-tag.adoc | 2 +- Documentation/git-write-tree.adoc | 2 +- 4 files changed, 51 insertions(+), 53 deletions(-) diff --git a/Documentation/git-daemon.adoc b/Documentation/git-daemon.adoc index bc3f77405e..99389f0388 100644 --- a/Documentation/git-daemon.adoc +++ b/Documentation/git-daemon.adoc @@ -36,13 +36,13 @@ pass some directory paths as `git daemon` arguments, the offers are limited to repositories within those directories. By default, only `upload-pack` service is enabled, which serves -'git fetch-pack' and 'git ls-remote' clients, which are invoked -from 'git fetch', 'git pull', and 'git clone'. +`git fetch-pack` and `git ls-remote` clients, which are invoked +from `git fetch`, `git pull`, and `git clone`. This is ideally suited for read-only updates, i.e., pulling from Git repositories. -An `upload-archive` also exists to serve 'git archive'. +An `upload-archive` also exists to serve `git archive`. OPTIONS ------- @@ -61,24 +61,24 @@ OPTIONS `--base-path-relaxed`:: If `--base-path` is enabled and repo lookup fails, with this option - 'git daemon' will attempt to lookup without prefixing the base path. + `git daemon` will attempt to lookup without prefixing the base path. This is useful for switching to `--base-path` usage, while still allowing the old paths. `--interpolated-path=<pathtemplate>`:: To support virtual hosting, an interpolated path template can be used to dynamically construct alternate paths. The template - supports %H for the target hostname as supplied by the client but - converted to all lowercase, %CH for the canonical hostname, - %IP for the server's IP address, %P for the port number, - and %D for the absolute path of the named repository. + supports `%H` for the target hostname as supplied by the client but + converted to all lowercase, `%CH` for the canonical hostname, + `%IP` for the server's IP address, `%P` for the port number, + and `%D` for the absolute path of the named repository. After interpolation, the path is validated against the directory list. `--export-all`:: Allow pulling from all directories that look like Git repositories (have the 'objects' and 'refs' subdirectories), even if they - do not have the 'git-daemon-export-ok' file. + do not have the `git-daemon-export-ok` file. `--inetd`:: Have the server run as an inetd service. Implies `--syslog` (may @@ -118,17 +118,17 @@ OPTIONS Send log messages to the specified destination. Note that this option does not imply `--verbose`, thus by default only error conditions will be logged. - The <destination> must be one of: + The _<destination>_ must be one of: + -- -stderr:: +`stderr`:: Write to standard error. Note that if `--detach` is specified, the process disconnects from the real standard error, making this destination effectively equivalent to `none`. -syslog:: +`syslog`:: Write to syslog, using the `git-daemon` identifier. -none:: +`none`:: Disable all logging. -- + @@ -149,7 +149,7 @@ otherwise `stderr`. Log details about the incoming connections and requested files. `--reuseaddr`:: - Use SO_REUSEADDR when binding the listening socket. + Use `SO_REUSEADDR` when binding the listening socket. This allows the server to restart without waiting for old connections to time out. @@ -157,7 +157,7 @@ otherwise `stderr`. Detach from the shell. Implies `--syslog`. `--pid-file=<file>`:: - Save the process id in 'file'. Ignored when the daemon + Save the process id in _<file>_. Ignored when the daemon is run under `--inetd`. `--user=<user>`:: @@ -170,14 +170,14 @@ otherwise `stderr`. + Giving these options is an error when used with `--inetd`; use the facility of inet daemon to achieve the same before spawning -'git daemon' if needed. +`git daemon` if needed. + Like many programs that switch user id, the daemon does not reset -environment variables such as `$HOME` when it runs git programs, +environment variables such as `HOME` when it runs git programs, e.g. `upload-pack` and `receive-pack`. When using this option, you may also want to set and export `HOME` to point at the home -directory of `<user>` before starting the daemon, and make sure any -Git configuration files in that directory are readable by `<user>`. +directory of _<user>_ before starting the daemon, and make sure any +Git configuration files in that directory are readable by _<user>_. `--enable=<service>`:: `--disable=<service>`:: @@ -206,8 +206,8 @@ Git configuration files in that directory are readable by `<user>`. `--access-hook=<path>`:: Every time a client connects, first run an external command specified by the <path> with service name (e.g. "upload-pack"), - path to the repository, hostname (%H), canonical hostname - (%CH), IP address (%IP), and TCP port (%P) as its command-line + path to the repository, hostname (`%H`), canonical hostname + (`%CH`), IP address (`%IP`), and TCP port (`%P`) as its command-line arguments. The external command can decide to decline the service by exiting with a non-zero status (or to allow it by exiting with a zero status). It can also look at the $REMOTE_ADDR @@ -218,7 +218,7 @@ The external command can optionally write a single line to its standard output to be sent to the requestor as an error message when it declines the service. -<directory>:: +_<directory>_:: The remaining arguments provide a list of directories. If any directories are specified, then the `git-daemon` process will serve a requested directory only if it is contained in one of @@ -230,24 +230,24 @@ SERVICES These services can be globally enabled/disabled using the command-line options of this command. If finer-grained -control is desired (e.g. to allow 'git archive' to be run +control is desired (e.g. to allow `git archive` to be run against only in a few selected repositories the daemon serves), the per-repository configuration file can be used to enable or disable them. upload-pack:: - This serves 'git fetch-pack' and 'git ls-remote' + This serves `git fetch-pack` and `git ls-remote` clients. It is enabled by default, but a repository can disable it by setting `daemon.uploadpack` configuration item to `false`. upload-archive:: - This serves 'git archive --remote'. It is disabled by + This serves `git archive --remote`. It is disabled by default, but a repository can enable it by setting `daemon.uploadarch` configuration item to `true`. receive-pack:: - This serves 'git send-pack' clients, allowing anonymous + This serves `git send-pack` clients, allowing anonymous push. It is disabled by default, as there is _no_ authentication in the protocol (in other words, anybody can push anything into the repository, including removal @@ -301,7 +301,7 @@ default repository could be made as well. 'git daemon' as regular daemon for virtual hosts:: - To set up 'git daemon' as a regular, non-inetd service that + To set up `git daemon` as a regular, non-inetd service that handles repositories for multiple virtual hosts based on their IP addresses, start the daemon like this: + @@ -318,7 +318,7 @@ Repositories can still be accessed by hostname though, assuming they correspond to these IP addresses. selectively enable/disable services per repository:: - To enable 'git archive --remote' and disable 'git fetch' against + To enable `git archive --remote` and disable `git fetch` against a repository, have the following in the configuration file in the repository (that is the file 'config' next to `HEAD`, 'refs' and 'objects'). @@ -332,8 +332,8 @@ selectively enable/disable services per repository:: ENVIRONMENT ----------- -'git daemon' will set REMOTE_ADDR to the IP address of the client -that connected to it, if the IP address is available. REMOTE_ADDR will +`git daemon` will set `REMOTE_ADDR` to the IP address of the client +that connected to it, if the IP address is available. `REMOTE_ADDR` will be available in the environment of hooks called when services are performed. diff --git a/Documentation/git-var.adoc b/Documentation/git-var.adoc index 909963b1c2..b606c2d649 100644 --- a/Documentation/git-var.adoc +++ b/Documentation/git-var.adoc @@ -32,58 +32,56 @@ EXAMPLES VARIABLES --------- -GIT_AUTHOR_IDENT:: +`GIT_AUTHOR_IDENT`:: The author of a piece of code. -GIT_COMMITTER_IDENT:: +`GIT_COMMITTER_IDENT`:: The person who put a piece of code into Git. -GIT_EDITOR:: +`GIT_EDITOR`:: Text editor for use by Git commands. The value is meant to be interpreted by the shell when it is used. Examples: `~/bin/vi`, `$SOME_ENVIRONMENT_VARIABLE`, `"C:\Program Files\Vim\gvim.exe" - --nofork`. The order of preference is the `$GIT_EDITOR` - environment variable, then `core.editor` configuration, then - `$VISUAL`, then `$EDITOR`, and then the default chosen at compile + --nofork`. The order of preference is `$GIT_EDITOR`, then + `core.editor` configuration value, then `$VISUAL`, then + `$EDITOR`, and then the default chosen at compile time, which is usually 'vi'. ifdef::git-default-editor[] The build you are using chose '{git-default-editor}' as the default. endif::git-default-editor[] -GIT_SEQUENCE_EDITOR:: +`GIT_SEQUENCE_EDITOR`:: Text editor used to edit the 'todo' file while running `git rebase -i`. Like `GIT_EDITOR`, the value is meant to be interpreted by - the shell when it is used. The order of preference is the - `$GIT_SEQUENCE_EDITOR` environment variable, then - `sequence.editor` configuration, and then the value of `git var - GIT_EDITOR`. + the shell when it is used. The order of preference is + `$GIT_SEQUENCE_EDITOR`, then `sequence.editor` configuration value, + and then the value of `git var GIT_EDITOR`. -GIT_PAGER:: +`GIT_PAGER`:: Text viewer for use by Git commands (e.g., 'less'). The value is meant to be interpreted by the shell. The order of preference - is the `$GIT_PAGER` environment variable, then `core.pager` - configuration, then `$PAGER`, and then the default chosen at - compile time (usually 'less'). + is `$GIT_PAGER`, then the value of `core.pager` configuration, then + `$PAGER`, and then the default chosen at compile time (usually `less`). ifdef::git-default-pager[] The build you are using chose '{git-default-pager}' as the default. endif::git-default-pager[] -GIT_DEFAULT_BRANCH:: +`GIT_DEFAULT_BRANCH`:: The name of the first branch created in newly initialized repositories. -GIT_SHELL_PATH:: +`GIT_SHELL_PATH`:: The path of the binary providing the POSIX shell for commands which use the shell. -GIT_ATTR_SYSTEM:: +`GIT_ATTR_SYSTEM`:: The path to the system linkgit:gitattributes[5] file, if one is enabled. -GIT_ATTR_GLOBAL:: +`GIT_ATTR_GLOBAL`:: The path to the global (per-user) linkgit:gitattributes[5] file. -GIT_CONFIG_SYSTEM:: +`GIT_CONFIG_SYSTEM`:: The path to the system configuration file, if one is enabled. -GIT_CONFIG_GLOBAL:: +`GIT_CONFIG_GLOBAL`:: The path to the global (per-user) configuration files, if any. Most path values contain only one value. However, some can contain multiple diff --git a/Documentation/git-verify-tag.adoc b/Documentation/git-verify-tag.adoc index ec995323f6..b3721a86f4 100644 --- a/Documentation/git-verify-tag.adoc +++ b/Documentation/git-verify-tag.adoc @@ -12,7 +12,7 @@ git verify-tag [-v | --verbose] [--format=<format>] [--raw] <tag>... DESCRIPTION ----------- -Validates the gpg signature created by 'git tag' in the tag +Validates the gpg signature created by `git tag` in the tag objects listed on the command line. OPTIONS diff --git a/Documentation/git-write-tree.adoc b/Documentation/git-write-tree.adoc index 4e1c3b9c0c..4c7100ea1e 100644 --- a/Documentation/git-write-tree.adoc +++ b/Documentation/git-write-tree.adoc @@ -34,7 +34,7 @@ OPTIONS `--prefix=<prefix>/`:: Writes a tree object that represents a subdirectory - `<prefix>`. This can be used to write the tree object + _<prefix>_. This can be used to write the tree object for a subproject that is in the named subdirectory. GIT -- 2.48.0 ^ permalink raw reply related [flat|nested] 26+ messages in thread
* Re: [PATCH] Additional changes 2025-05-07 20:58 ` [PATCH] " Jean-Noël Avila @ 2025-05-08 15:14 ` Junio C Hamano 2025-05-09 12:12 ` Jean-Noël AVILA 0 siblings, 1 reply; 26+ messages in thread From: Junio C Hamano @ 2025-05-08 15:14 UTC (permalink / raw) To: Jean-Noël Avila; +Cc: git Jean-Noël Avila <jn.avila@free.fr> writes: > --- > Documentation/git-daemon.adoc | 60 +++++++++++++++---------------- > Documentation/git-var.adoc | 40 ++++++++++----------- > Documentation/git-verify-tag.adoc | 2 +- > Documentation/git-write-tree.adoc | 2 +- > 4 files changed, 51 insertions(+), 53 deletions(-) I was somewhat confused where this patch is designed to apply, but I think I figured it out. These are to further update on top of my synopsis related mark-up updates. Do you mean this as a set of review comment, i.e. I am expected to spilt them into parts and fold them into those three commits to produce an updated version of those three patches with "Helped-by:" attributing you? Or do you want this to sit on top of the 3-patch series separately as the 4th patch? If the latter we'd need a log message plus sign-off. I'd assume it is the former (as the three-patch series hasn't hit 'next' yet) and start updating htese three patches. Thanks. ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH] Additional changes 2025-05-08 15:14 ` Junio C Hamano @ 2025-05-09 12:12 ` Jean-Noël AVILA 2025-05-09 14:35 ` Junio C Hamano 0 siblings, 1 reply; 26+ messages in thread From: Jean-Noël AVILA @ 2025-05-09 12:12 UTC (permalink / raw) To: Junio C Hamano; +Cc: git On Thursday, 8 May 2025 17:14:40 CEST Junio C Hamano wrote: > Jean-Noël Avila <jn.avila@free.fr> writes: > > --- > > > > Documentation/git-daemon.adoc | 60 +++++++++++++++---------------- > > Documentation/git-var.adoc | 40 ++++++++++----------- > > Documentation/git-verify-tag.adoc | 2 +- > > Documentation/git-write-tree.adoc | 2 +- > > 4 files changed, 51 insertions(+), 53 deletions(-) > > I was somewhat confused where this patch is designed to apply, but I > think I figured it out. These are to further update on top of my > synopsis related mark-up updates. > > Do you mean this as a set of review comment, i.e. I am expected to > spilt them into parts and fold them into those three commits to > produce an updated version of those three patches with "Helped-by:" > attributing you? > > Or do you want this to sit on top of the 3-patch series separately > as the 4th patch? If the latter we'd need a log message plus > sign-off. > > I'd assume it is the former (as the three-patch series hasn't hit > 'next' yet) and start updating htese three patches. > > Thanks. Sorry for not being clear. I was wary of what the provided patches did not address, so I reviewed after applying your series and bundled it in another patch, which was not signed off on purpose. Of course, the proposed changes can be discussed. If you prefer, I can dispatch them and propose a v3. Thanks, JN ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH] Additional changes 2025-05-09 12:12 ` Jean-Noël AVILA @ 2025-05-09 14:35 ` Junio C Hamano 2025-05-09 17:08 ` Jean-Noël AVILA 0 siblings, 1 reply; 26+ messages in thread From: Junio C Hamano @ 2025-05-09 14:35 UTC (permalink / raw) To: Jean-Noël AVILA; +Cc: git Jean-Noël AVILA <jn.avila@free.fr> writes: >> I'd assume it is the former (as the three-patch series hasn't hit >> 'next' yet) and start updating htese three patches. >> >> Thanks. > > Sorry for not being clear. I was wary of what the provided patches did not > address, so I reviewed after applying your series and bundled it in another > patch, which was not signed off on purpose. I see. In the original, I deliberately ignored what the patches did not address ;-) as I wanted to limit the scope of the changes to reduce the number of things the reviewers need to look for. In any case, i assumed the former and squashed your changes (which looked all sensible) and the result is what is in my tree right now (but it can be further modified as the series is not yet in 'next'). > Of course, the proposed changes can be discussed. If you prefer, I can > dispatch them and propose a v3. Surely. Are there particular things that you were either unsure about (which may lead to possible partial retraction) or want to stress on (which would help other developers and reviewers recall what they need to watch out for when touching the documentation)? Thanks. ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH] Additional changes 2025-05-09 14:35 ` Junio C Hamano @ 2025-05-09 17:08 ` Jean-Noël AVILA 2025-05-09 18:24 ` Junio C Hamano 0 siblings, 1 reply; 26+ messages in thread From: Jean-Noël AVILA @ 2025-05-09 17:08 UTC (permalink / raw) To: Junio C Hamano; +Cc: git On Friday, 9 May 2025 16:35:42 CEST Junio C Hamano wrote: > Surely. Are there particular things that you were either unsure > about (which may lead to possible partial retraction) or want to > stress on (which would help other developers and reviewers recall > what they need to watch out for when touching the documentation)? > Now that you're asking, the heavy additional changes to git-var's manpage are mainly targeted at clearing out some misuses of $ENV_VAR vs ENV_VAR as I see them. Others can disagree. Maybe these changes should go into a separated patch because they do not really fit with the "new style" changes. Thanks ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: [PATCH] Additional changes 2025-05-09 17:08 ` Jean-Noël AVILA @ 2025-05-09 18:24 ` Junio C Hamano 0 siblings, 0 replies; 26+ messages in thread From: Junio C Hamano @ 2025-05-09 18:24 UTC (permalink / raw) To: Jean-Noël AVILA; +Cc: git Jean-Noël AVILA <jn.avila@free.fr> writes: > On Friday, 9 May 2025 16:35:42 CEST Junio C Hamano wrote: >> Surely. Are there particular things that you were either unsure >> about (which may lead to possible partial retraction) or want to >> stress on (which would help other developers and reviewers recall >> what they need to watch out for when touching the documentation)? >> > > Now that you're asking, the heavy additional changes to git-var's manpage are > mainly targeted at clearing out some misuses of $ENV_VAR vs ENV_VAR as I see > them. Others can disagree. > > Maybe these changes should go into a separated patch because they do not > really fit with the "new style" changes. OK, then I'll revert the changes from these three patches I squashed your additional changes in, so that we can have a separate series to clean up "$ENV_VAR vs ENV_VAR" (Documentation/CodingGuidelines tells us when to use and not to use "$", which is quite useful), perhaps? Thanks. ^ permalink raw reply [flat|nested] 26+ messages in thread
* [PATCH v3 0/4] Additional changes 2025-05-01 21:34 [PATCH 0/4] A handful of doc synopsis/options update Junio C Hamano ` (4 preceding siblings ...) 2025-05-03 1:15 ` [PATCH v2 0/3] A handful of doc synopsis/options update Junio C Hamano @ 2025-05-10 12:33 ` Jean-Noël Avila 2025-05-10 12:33 ` [PATCH v3 1/4] git-daemon doc: update mark-up of synopsis option descriptions Jean-Noël Avila ` (3 more replies) 5 siblings, 4 replies; 26+ messages in thread From: Jean-Noël Avila @ 2025-05-10 12:33 UTC (permalink / raw) To: Junio C Hamano, git; +Cc: Jean-Noël Avila This series is just applying additional 'new style' changes on top of the previous versions. Another patch is added to fix $ENV_VAR vs ENV_VAR misuse. Jean-Noël Avila (1): git-var doc: fix usage of $ENV_VAR vs ENV_VAR Junio C Hamano (3): git-daemon doc: update mark-up of synopsis option descriptions git-{var,write-tree} docs: update mark-up of synopsis option descriptions git-verify-* doc: update mark-up of synopsis option descriptions Documentation/git-daemon.adoc | 181 ++++++++++++++------------- Documentation/git-var.adoc | 46 ++++--- Documentation/git-verify-commit.adoc | 16 ++- Documentation/git-verify-pack.adoc | 28 ++--- Documentation/git-verify-tag.adoc | 16 ++- Documentation/git-write-tree.adoc | 18 +-- 6 files changed, 148 insertions(+), 157 deletions(-) -- 2.48.0 ^ permalink raw reply [flat|nested] 26+ messages in thread
* [PATCH v3 1/4] git-daemon doc: update mark-up of synopsis option descriptions 2025-05-10 12:33 ` [PATCH v3 0/4] " Jean-Noël Avila @ 2025-05-10 12:33 ` Jean-Noël Avila 2025-05-10 12:33 ` [PATCH v3 2/4] git-{var,write-tree} docs: " Jean-Noël Avila ` (2 subsequent siblings) 3 siblings, 0 replies; 26+ messages in thread From: Jean-Noël Avila @ 2025-05-10 12:33 UTC (permalink / raw) To: Junio C Hamano, git; +Cc: Jean-Noël Avila From: Junio C Hamano <gitster@pobox.com> To unify mark-up used in our documentation to a newer convention, started by 22293895 (doc: apply synopsis simplification on git-clone and git-init, 2024-09-24), update the documentation of 'git daemon' to * use [synopsis], not [verse] in the SYNOPSIS section * enclose `--option=<value>` in backquotes Also, split '--[no-]option' into '--option' and '--no-option' to make it easier to grep for them. Signed-off-by: Junio C Hamano <gitster@pobox.com> Helped-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/git-daemon.adoc | 181 +++++++++++++++++----------------- 1 file changed, 91 insertions(+), 90 deletions(-) diff --git a/Documentation/git-daemon.adoc b/Documentation/git-daemon.adoc index ede7b935d6..99389f0388 100644 --- a/Documentation/git-daemon.adoc +++ b/Documentation/git-daemon.adoc @@ -7,21 +7,21 @@ git-daemon - A really simple server for Git repositories SYNOPSIS -------- -[verse] -'git daemon' [--verbose] [--syslog] [--export-all] - [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>] - [--strict-paths] [--base-path=<path>] [--base-path-relaxed] - [--user-path | --user-path=<path>] - [--interpolated-path=<pathtemplate>] - [--reuseaddr] [--detach] [--pid-file=<file>] - [--enable=<service>] [--disable=<service>] - [--allow-override=<service>] [--forbid-override=<service>] - [--access-hook=<path>] [--[no-]informative-errors] - [--inetd | - [--listen=<host-or-ipaddr>] [--port=<n>] - [--user=<user> [--group=<group>]]] - [--log-destination=(stderr|syslog|none)] - [<directory>...] +[synopsis] +git daemon [--verbose] [--syslog] [--export-all] + [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>] + [--strict-paths] [--base-path=<path>] [--base-path-relaxed] + [--user-path | --user-path=<path>] + [--interpolated-path=<pathtemplate>] + [--reuseaddr] [--detach] [--pid-file=<file>] + [--enable=<service>] [--disable=<service>] + [--allow-override=<service>] [--forbid-override=<service>] + [--access-hook=<path>] [--[no-]informative-errors] + [--inetd | + [--listen=<host-or-ipaddr>] [--port=<n>] + [--user=<user> [--group=<group>]]] + [--log-destination=(stderr|syslog|none)] + [<directory>...] DESCRIPTION ----------- @@ -32,111 +32,111 @@ that service if it is enabled. It verifies that the directory has the magic file "git-daemon-export-ok", and it will refuse to export any Git directory that hasn't explicitly been marked for export this way (unless the `--export-all` parameter is specified). If you -pass some directory paths as 'git daemon' arguments, the offers are limited to +pass some directory paths as `git daemon` arguments, the offers are limited to repositories within those directories. By default, only `upload-pack` service is enabled, which serves -'git fetch-pack' and 'git ls-remote' clients, which are invoked -from 'git fetch', 'git pull', and 'git clone'. +`git fetch-pack` and `git ls-remote` clients, which are invoked +from `git fetch`, `git pull`, and `git clone`. This is ideally suited for read-only updates, i.e., pulling from Git repositories. -An `upload-archive` also exists to serve 'git archive'. +An `upload-archive` also exists to serve `git archive`. OPTIONS ------- ---strict-paths:: +`--strict-paths`:: Match paths exactly (i.e. don't allow "/foo/repo" when the real path is "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths. - 'git daemon' will refuse to start when this option is enabled and no + `git daemon` will refuse to start when this option is enabled and no directory arguments are provided. ---base-path=<path>:: +`--base-path=<path>`:: Remap all the path requests as relative to the given path. - This is sort of "Git root" - if you run 'git daemon' with - '--base-path=/srv/git' on example.com, then if you later try to pull - 'git://example.com/hello.git', 'git daemon' will interpret the path - as `/srv/git/hello.git`. - ---base-path-relaxed:: - If --base-path is enabled and repo lookup fails, with this option - 'git daemon' will attempt to lookup without prefixing the base path. - This is useful for switching to --base-path usage, while still + This is sort of "Git root" - if you run `git daemon` with + `--base-path=/srv/git` on `example.com`, then if you later try + to pull from `git://example.com/hello.git`, `git daemon` will + interpret the path as `/srv/git/hello.git`. + +`--base-path-relaxed`:: + If `--base-path` is enabled and repo lookup fails, with this option + `git daemon` will attempt to lookup without prefixing the base path. + This is useful for switching to `--base-path` usage, while still allowing the old paths. ---interpolated-path=<pathtemplate>:: +`--interpolated-path=<pathtemplate>`:: To support virtual hosting, an interpolated path template can be used to dynamically construct alternate paths. The template - supports %H for the target hostname as supplied by the client but - converted to all lowercase, %CH for the canonical hostname, - %IP for the server's IP address, %P for the port number, - and %D for the absolute path of the named repository. + supports `%H` for the target hostname as supplied by the client but + converted to all lowercase, `%CH` for the canonical hostname, + `%IP` for the server's IP address, `%P` for the port number, + and `%D` for the absolute path of the named repository. After interpolation, the path is validated against the directory list. ---export-all:: +`--export-all`:: Allow pulling from all directories that look like Git repositories (have the 'objects' and 'refs' subdirectories), even if they - do not have the 'git-daemon-export-ok' file. + do not have the `git-daemon-export-ok` file. ---inetd:: - Have the server run as an inetd service. Implies --syslog (may be - overridden with `--log-destination=`). - Incompatible with --detach, --port, --listen, --user and --group - options. +`--inetd`:: + Have the server run as an inetd service. Implies `--syslog` (may + be overridden with `--log-destination=`). + Incompatible with `--detach`, `--port`, `--listen`, `--user` and + `--group` options. ---listen=<host-or-ipaddr>:: +`--listen=<host-or-ipaddr>`:: Listen on a specific IP address or hostname. IP addresses can be either an IPv4 address or an IPv6 address if supported. If IPv6 - is not supported, then --listen=<hostname> is also not supported and - --listen must be given an IPv4 address. + is not supported, then `--listen=<hostname>` is also not supported + and `--listen` must be given an IPv4 address. Can be given more than once. Incompatible with `--inetd` option. ---port=<n>:: +`--port=<n>`:: Listen on an alternative port. Incompatible with `--inetd` option. ---init-timeout=<n>:: +`--init-timeout=<n>`:: Timeout (in seconds) between the moment the connection is established and the client request is received (typically a rather low value, since that should be basically immediate). ---timeout=<n>:: +`--timeout=<n>`:: Timeout (in seconds) for specific client sub-requests. This includes the time it takes for the server to process the sub-request and the time spent waiting for the next client's request. ---max-connections=<n>:: +`--max-connections=<n>`:: Maximum number of concurrent clients, defaults to 32. Set it to zero for no limit. ---syslog:: +`--syslog`:: Short for `--log-destination=syslog`. ---log-destination=<destination>:: +`--log-destination=<destination>`:: Send log messages to the specified destination. - Note that this option does not imply --verbose, + Note that this option does not imply `--verbose`, thus by default only error conditions will be logged. - The <destination> must be one of: + The _<destination>_ must be one of: + -- -stderr:: +`stderr`:: Write to standard error. Note that if `--detach` is specified, the process disconnects from the real standard error, making this destination effectively equivalent to `none`. -syslog:: +`syslog`:: Write to syslog, using the `git-daemon` identifier. -none:: +`none`:: Disable all logging. -- + The default destination is `syslog` if `--inetd` or `--detach` is specified, otherwise `stderr`. ---user-path:: ---user-path=<path>:: +`--user-path`:: +`--user-path=<path>`:: Allow {tilde}user notation to be used in requests. When specified with no parameter, a request to git://host/{tilde}alice/foo is taken as a request to access @@ -145,23 +145,23 @@ otherwise `stderr`. taken as a request to access `<path>/foo` repository in the home directory of user `alice`. ---verbose:: +`--verbose`:: Log details about the incoming connections and requested files. ---reuseaddr:: - Use SO_REUSEADDR when binding the listening socket. +`--reuseaddr`:: + Use `SO_REUSEADDR` when binding the listening socket. This allows the server to restart without waiting for old connections to time out. ---detach:: - Detach from the shell. Implies --syslog. +`--detach`:: + Detach from the shell. Implies `--syslog`. ---pid-file=<file>:: - Save the process id in 'file'. Ignored when the daemon +`--pid-file=<file>`:: + Save the process id in _<file>_. Ignored when the daemon is run under `--inetd`. ---user=<user>:: ---group=<group>:: +`--user=<user>`:: +`--group=<group>`:: Change daemon's uid and gid before entering the service loop. When only `--user` is given without `--group`, the primary group ID for the user is used. The values of @@ -170,43 +170,44 @@ otherwise `stderr`. + Giving these options is an error when used with `--inetd`; use the facility of inet daemon to achieve the same before spawning -'git daemon' if needed. +`git daemon` if needed. + Like many programs that switch user id, the daemon does not reset -environment variables such as `$HOME` when it runs git programs, +environment variables such as `HOME` when it runs git programs, e.g. `upload-pack` and `receive-pack`. When using this option, you may also want to set and export `HOME` to point at the home -directory of `<user>` before starting the daemon, and make sure any -Git configuration files in that directory are readable by `<user>`. +directory of _<user>_ before starting the daemon, and make sure any +Git configuration files in that directory are readable by _<user>_. ---enable=<service>:: ---disable=<service>:: +`--enable=<service>`:: +`--disable=<service>`:: Enable/disable the service site-wide per default. Note that a service disabled site-wide can still be enabled per repository if it is marked overridable and the repository enables the service with a configuration item. ---allow-override=<service>:: ---forbid-override=<service>:: +`--allow-override=<service>`:: +`--forbid-override=<service>`:: Allow/forbid overriding the site-wide default with per repository configuration. By default, all the services may be overridden. ---[no-]informative-errors:: +`--informative-errors`:: +`--no-informative-errors`:: When informative errors are turned on, git-daemon will report more verbose errors to the client, differentiating conditions like "no such repository" from "repository not exported". This is more convenient for clients, but may leak information about the existence of unexported repositories. When informative errors are not enabled, all errors report "access denied" to the - client. The default is --no-informative-errors. + client. The default is `--no-informative-errors`. ---access-hook=<path>:: +`--access-hook=<path>`:: Every time a client connects, first run an external command specified by the <path> with service name (e.g. "upload-pack"), - path to the repository, hostname (%H), canonical hostname - (%CH), IP address (%IP), and TCP port (%P) as its command-line + path to the repository, hostname (`%H`), canonical hostname + (`%CH`), IP address (`%IP`), and TCP port (`%P`) as its command-line arguments. The external command can decide to decline the service by exiting with a non-zero status (or to allow it by exiting with a zero status). It can also look at the $REMOTE_ADDR @@ -217,7 +218,7 @@ The external command can optionally write a single line to its standard output to be sent to the requestor as an error message when it declines the service. -<directory>:: +_<directory>_:: The remaining arguments provide a list of directories. If any directories are specified, then the `git-daemon` process will serve a requested directory only if it is contained in one of @@ -229,24 +230,24 @@ SERVICES These services can be globally enabled/disabled using the command-line options of this command. If finer-grained -control is desired (e.g. to allow 'git archive' to be run +control is desired (e.g. to allow `git archive` to be run against only in a few selected repositories the daemon serves), the per-repository configuration file can be used to enable or disable them. upload-pack:: - This serves 'git fetch-pack' and 'git ls-remote' + This serves `git fetch-pack` and `git ls-remote` clients. It is enabled by default, but a repository can disable it by setting `daemon.uploadpack` configuration item to `false`. upload-archive:: - This serves 'git archive --remote'. It is disabled by + This serves `git archive --remote`. It is disabled by default, but a repository can enable it by setting `daemon.uploadarch` configuration item to `true`. receive-pack:: - This serves 'git send-pack' clients, allowing anonymous + This serves `git send-pack` clients, allowing anonymous push. It is disabled by default, as there is _no_ authentication in the protocol (in other words, anybody can push anything into the repository, including removal @@ -300,7 +301,7 @@ default repository could be made as well. 'git daemon' as regular daemon for virtual hosts:: - To set up 'git daemon' as a regular, non-inetd service that + To set up `git daemon` as a regular, non-inetd service that handles repositories for multiple virtual hosts based on their IP addresses, start the daemon like this: + @@ -317,7 +318,7 @@ Repositories can still be accessed by hostname though, assuming they correspond to these IP addresses. selectively enable/disable services per repository:: - To enable 'git archive --remote' and disable 'git fetch' against + To enable `git archive --remote` and disable `git fetch` against a repository, have the following in the configuration file in the repository (that is the file 'config' next to `HEAD`, 'refs' and 'objects'). @@ -331,8 +332,8 @@ selectively enable/disable services per repository:: ENVIRONMENT ----------- -'git daemon' will set REMOTE_ADDR to the IP address of the client -that connected to it, if the IP address is available. REMOTE_ADDR will +`git daemon` will set `REMOTE_ADDR` to the IP address of the client +that connected to it, if the IP address is available. `REMOTE_ADDR` will be available in the environment of hooks called when services are performed. -- 2.48.0 ^ permalink raw reply related [flat|nested] 26+ messages in thread
* [PATCH v3 2/4] git-{var,write-tree} docs: update mark-up of synopsis option descriptions 2025-05-10 12:33 ` [PATCH v3 0/4] " Jean-Noël Avila 2025-05-10 12:33 ` [PATCH v3 1/4] git-daemon doc: update mark-up of synopsis option descriptions Jean-Noël Avila @ 2025-05-10 12:33 ` Jean-Noël Avila 2025-05-10 12:33 ` [PATCH v3 3/4] git-verify-* doc: " Jean-Noël Avila 2025-05-10 12:33 ` [PATCH v3 4/4] git-var doc: fix usage of $ENV_VAR vs ENV_VAR Jean-Noël Avila 3 siblings, 0 replies; 26+ messages in thread From: Jean-Noël Avila @ 2025-05-10 12:33 UTC (permalink / raw) To: Junio C Hamano, git; +Cc: Jean-Noël Avila From: Junio C Hamano <gitster@pobox.com> To unify mark-up used in our documentation to a newer convention, started by 22293895 (doc: apply synopsis simplification on git-clone and git-init, 2024-09-24), update the documentation for 'git var' and 'git write-tree' to * use [synopsis], not [verse] in the SYNOPSIS section * enclose `--option=<value>` in backquotes Signed-off-by: Junio C Hamano <gitster@pobox.com> Helped-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/git-var.adoc | 6 +++--- Documentation/git-write-tree.adoc | 18 +++++++++--------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/Documentation/git-var.adoc b/Documentation/git-var.adoc index 0680568dfd..909963b1c2 100644 --- a/Documentation/git-var.adoc +++ b/Documentation/git-var.adoc @@ -8,8 +8,8 @@ git-var - Show a Git logical variable SYNOPSIS -------- -[verse] -'git var' (-l | <variable>) +[synopsis] +git var (-l | <variable>) DESCRIPTION ----------- @@ -18,7 +18,7 @@ no value. OPTIONS ------- --l:: +`-l`:: Display the logical variables. In addition, all the variables of the Git configuration file .git/config are listed as well. (However, the configuration variables listing functionality diff --git a/Documentation/git-write-tree.adoc b/Documentation/git-write-tree.adoc index f22041a9dc..4c7100ea1e 100644 --- a/Documentation/git-write-tree.adoc +++ b/Documentation/git-write-tree.adoc @@ -8,8 +8,8 @@ git-write-tree - Create a tree object from the current index SYNOPSIS -------- -[verse] -'git write-tree' [--missing-ok] [--prefix=<prefix>/] +[synopsis] +git write-tree [--missing-ok] [--prefix=<prefix>/] DESCRIPTION ----------- @@ -18,23 +18,23 @@ tree object is printed to standard output. The index must be in a fully merged state. -Conceptually, 'git write-tree' sync()s the current index contents +Conceptually, `git write-tree` sync()s the current index contents into a set of tree files. In order to have that match what is actually in your directory right -now, you need to have done a 'git update-index' phase before you did the -'git write-tree'. +now, you need to have done a `git update-index` phase before you did the +`git write-tree`. OPTIONS ------- ---missing-ok:: - Normally 'git write-tree' ensures that the objects referenced by the +`--missing-ok`:: + Normally `git write-tree` ensures that the objects referenced by the directory exist in the object database. This option disables this check. ---prefix=<prefix>/:: +`--prefix=<prefix>/`:: Writes a tree object that represents a subdirectory - `<prefix>`. This can be used to write the tree object + _<prefix>_. This can be used to write the tree object for a subproject that is in the named subdirectory. GIT -- 2.48.0 ^ permalink raw reply related [flat|nested] 26+ messages in thread
* [PATCH v3 3/4] git-verify-* doc: update mark-up of synopsis option descriptions 2025-05-10 12:33 ` [PATCH v3 0/4] " Jean-Noël Avila 2025-05-10 12:33 ` [PATCH v3 1/4] git-daemon doc: update mark-up of synopsis option descriptions Jean-Noël Avila 2025-05-10 12:33 ` [PATCH v3 2/4] git-{var,write-tree} docs: " Jean-Noël Avila @ 2025-05-10 12:33 ` Jean-Noël Avila 2025-05-10 12:33 ` [PATCH v3 4/4] git-var doc: fix usage of $ENV_VAR vs ENV_VAR Jean-Noël Avila 3 siblings, 0 replies; 26+ messages in thread From: Jean-Noël Avila @ 2025-05-10 12:33 UTC (permalink / raw) To: Junio C Hamano, git; +Cc: Jean-Noël Avila From: Junio C Hamano <gitster@pobox.com> To unify mark-up used in our documentation to a newer convention, started by 22293895 (doc: apply synopsis simplification on git-clone and git-init, 2024-09-24), update the documentation pages for 'git verify-commit', 'git verify-tag', and 'git verify-pack' to * use [synopsis], not [verse] in the SYNOPSIS section * enclose `--option=<value>` in backquotes * do not describe non-option arguments in the OPTIONS section Signed-off-by: Junio C Hamano <gitster@pobox.com> Helped-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/git-verify-commit.adoc | 16 +++++++--------- Documentation/git-verify-pack.adoc | 28 ++++++++++++---------------- Documentation/git-verify-tag.adoc | 16 +++++++--------- 3 files changed, 26 insertions(+), 34 deletions(-) diff --git a/Documentation/git-verify-commit.adoc b/Documentation/git-verify-commit.adoc index aee4c40eac..ff5b8b97ef 100644 --- a/Documentation/git-verify-commit.adoc +++ b/Documentation/git-verify-commit.adoc @@ -7,26 +7,24 @@ git-verify-commit - Check the GPG signature of commits SYNOPSIS -------- -[verse] -'git verify-commit' [-v | --verbose] [--raw] <commit>... +[synopsis] +git verify-commit [-v | --verbose] [--raw] <commit>... DESCRIPTION ----------- -Validates the GPG signature created by 'git commit -S'. +Validates the GPG signature created by `git commit -S` +on the commit objects given on the command line. OPTIONS ------- ---raw:: +`--raw`:: Print the raw gpg status output to standard error instead of the normal human-readable output. --v:: ---verbose:: +`-v`:: +`--verbose`:: Print the contents of the commit object before validating it. -<commit>...:: - SHA-1 identifiers of Git commit objects. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-verify-pack.adoc b/Documentation/git-verify-pack.adoc index d7e886918a..b0462d8db3 100644 --- a/Documentation/git-verify-pack.adoc +++ b/Documentation/git-verify-pack.adoc @@ -8,43 +8,39 @@ git-verify-pack - Validate packed Git archive files SYNOPSIS -------- -[verse] -'git verify-pack' [-v | --verbose] [-s | --stat-only] [--] <pack>.idx... +[synopsis] +git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx... DESCRIPTION ----------- -Reads given idx file for packed Git archive created with the -'git pack-objects' command and verifies the idx file and the -corresponding pack file. +Read each idx file for packed Git archive given on the command line, +and verify the idx file and the corresponding pack file. OPTIONS ------- -<pack>.idx ...:: - The idx files to verify. - --v:: ---verbose:: +`-v`:: +`--verbose`:: After verifying the pack, show the list of objects contained in the pack and a histogram of delta chain length. --s:: ---stat-only:: +`-s`:: +`--stat-only`:: Do not verify the pack contents; only show the histogram of delta chain length. With `--verbose`, the list of objects is also shown. -\--:: +`--`:: Do not interpret any more arguments as options. OUTPUT FORMAT ------------- -When specifying the -v option the format used is: +When specifying the `-v` option the format used is: - SHA-1 type size size-in-packfile offset-in-packfile + object-name type size size-in-packfile offset-in-packfile for objects that are not deltified in the pack, and - SHA-1 type size size-in-packfile offset-in-packfile depth base-SHA-1 + object-name type size size-in-packfile offset-in-packfile depth base-object-name for objects that are deltified. diff --git a/Documentation/git-verify-tag.adoc b/Documentation/git-verify-tag.adoc index 81d50ecc4c..b3721a86f4 100644 --- a/Documentation/git-verify-tag.adoc +++ b/Documentation/git-verify-tag.adoc @@ -7,26 +7,24 @@ git-verify-tag - Check the GPG signature of tags SYNOPSIS -------- -[verse] -'git verify-tag' [-v | --verbose] [--format=<format>] [--raw] <tag>... +[synopsis] +git verify-tag [-v | --verbose] [--format=<format>] [--raw] <tag>... DESCRIPTION ----------- -Validates the gpg signature created by 'git tag'. +Validates the gpg signature created by `git tag` in the tag +objects listed on the command line. OPTIONS ------- ---raw:: +`--raw`:: Print the raw gpg status output to standard error instead of the normal human-readable output. --v:: ---verbose:: +`-v`:: +`--verbose`:: Print the contents of the tag object before validating it. -<tag>...:: - SHA-1 identifiers of Git tag objects. - GIT --- Part of the linkgit:git[1] suite -- 2.48.0 ^ permalink raw reply related [flat|nested] 26+ messages in thread
* [PATCH v3 4/4] git-var doc: fix usage of $ENV_VAR vs ENV_VAR 2025-05-10 12:33 ` [PATCH v3 0/4] " Jean-Noël Avila ` (2 preceding siblings ...) 2025-05-10 12:33 ` [PATCH v3 3/4] git-verify-* doc: " Jean-Noël Avila @ 2025-05-10 12:33 ` Jean-Noël Avila 3 siblings, 0 replies; 26+ messages in thread From: Jean-Noël Avila @ 2025-05-10 12:33 UTC (permalink / raw) To: Junio C Hamano, git; +Cc: Jean-Noël Avila When refering to environment variables in the documentation, use the ENV_VARIABLE format instead of $ENV_VARIABLE. The latter is used in the documentation to refer to the actual value of the variable, not the name of the variable. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> --- Documentation/git-var.adoc | 40 ++++++++++++++++++-------------------- 1 file changed, 19 insertions(+), 21 deletions(-) diff --git a/Documentation/git-var.adoc b/Documentation/git-var.adoc index 909963b1c2..b606c2d649 100644 --- a/Documentation/git-var.adoc +++ b/Documentation/git-var.adoc @@ -32,58 +32,56 @@ EXAMPLES VARIABLES --------- -GIT_AUTHOR_IDENT:: +`GIT_AUTHOR_IDENT`:: The author of a piece of code. -GIT_COMMITTER_IDENT:: +`GIT_COMMITTER_IDENT`:: The person who put a piece of code into Git. -GIT_EDITOR:: +`GIT_EDITOR`:: Text editor for use by Git commands. The value is meant to be interpreted by the shell when it is used. Examples: `~/bin/vi`, `$SOME_ENVIRONMENT_VARIABLE`, `"C:\Program Files\Vim\gvim.exe" - --nofork`. The order of preference is the `$GIT_EDITOR` - environment variable, then `core.editor` configuration, then - `$VISUAL`, then `$EDITOR`, and then the default chosen at compile + --nofork`. The order of preference is `$GIT_EDITOR`, then + `core.editor` configuration value, then `$VISUAL`, then + `$EDITOR`, and then the default chosen at compile time, which is usually 'vi'. ifdef::git-default-editor[] The build you are using chose '{git-default-editor}' as the default. endif::git-default-editor[] -GIT_SEQUENCE_EDITOR:: +`GIT_SEQUENCE_EDITOR`:: Text editor used to edit the 'todo' file while running `git rebase -i`. Like `GIT_EDITOR`, the value is meant to be interpreted by - the shell when it is used. The order of preference is the - `$GIT_SEQUENCE_EDITOR` environment variable, then - `sequence.editor` configuration, and then the value of `git var - GIT_EDITOR`. + the shell when it is used. The order of preference is + `$GIT_SEQUENCE_EDITOR`, then `sequence.editor` configuration value, + and then the value of `git var GIT_EDITOR`. -GIT_PAGER:: +`GIT_PAGER`:: Text viewer for use by Git commands (e.g., 'less'). The value is meant to be interpreted by the shell. The order of preference - is the `$GIT_PAGER` environment variable, then `core.pager` - configuration, then `$PAGER`, and then the default chosen at - compile time (usually 'less'). + is `$GIT_PAGER`, then the value of `core.pager` configuration, then + `$PAGER`, and then the default chosen at compile time (usually `less`). ifdef::git-default-pager[] The build you are using chose '{git-default-pager}' as the default. endif::git-default-pager[] -GIT_DEFAULT_BRANCH:: +`GIT_DEFAULT_BRANCH`:: The name of the first branch created in newly initialized repositories. -GIT_SHELL_PATH:: +`GIT_SHELL_PATH`:: The path of the binary providing the POSIX shell for commands which use the shell. -GIT_ATTR_SYSTEM:: +`GIT_ATTR_SYSTEM`:: The path to the system linkgit:gitattributes[5] file, if one is enabled. -GIT_ATTR_GLOBAL:: +`GIT_ATTR_GLOBAL`:: The path to the global (per-user) linkgit:gitattributes[5] file. -GIT_CONFIG_SYSTEM:: +`GIT_CONFIG_SYSTEM`:: The path to the system configuration file, if one is enabled. -GIT_CONFIG_GLOBAL:: +`GIT_CONFIG_GLOBAL`:: The path to the global (per-user) configuration files, if any. Most path values contain only one value. However, some can contain multiple -- 2.48.0 ^ permalink raw reply related [flat|nested] 26+ messages in thread
end of thread, other threads:[~2025-05-10 12:34 UTC | newest]
Thread overview: 26+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2025-05-01 21:34 [PATCH 0/4] A handful of doc synopsis/options update Junio C Hamano
2025-05-01 21:34 ` [PATCH 1/4] git-verify-* doc: update mark-up of synopsis option descriptions Junio C Hamano
2025-05-01 22:43 ` Eric Sunshine
2025-05-01 23:10 ` Junio C Hamano
2025-05-01 21:34 ` [PATCH 2/4] git-{var,write-tree} docs: " Junio C Hamano
2025-05-01 21:34 ` [PATCH 3/4] git-daemon doc: " Junio C Hamano
2025-05-01 22:52 ` Eric Sunshine
2025-05-01 23:12 ` Junio C Hamano
2025-05-01 23:22 ` Junio C Hamano
2025-05-01 21:34 ` [WIP PATCH 4/4] git-worktree " Junio C Hamano
2025-05-03 1:15 ` [PATCH v2 0/3] A handful of doc synopsis/options update Junio C Hamano
2025-05-03 1:15 ` [PATCH v2 1/3] git-verify-* doc: update mark-up of synopsis option descriptions Junio C Hamano
2025-05-03 1:15 ` [PATCH v2 2/3] git-{var,write-tree} docs: " Junio C Hamano
2025-05-03 1:15 ` [PATCH v2 3/3] git-daemon doc: " Junio C Hamano
2025-05-07 20:58 ` Additional changes Jean-Noël Avila
2025-05-07 20:58 ` [PATCH] " Jean-Noël Avila
2025-05-08 15:14 ` Junio C Hamano
2025-05-09 12:12 ` Jean-Noël AVILA
2025-05-09 14:35 ` Junio C Hamano
2025-05-09 17:08 ` Jean-Noël AVILA
2025-05-09 18:24 ` Junio C Hamano
2025-05-10 12:33 ` [PATCH v3 0/4] " Jean-Noël Avila
2025-05-10 12:33 ` [PATCH v3 1/4] git-daemon doc: update mark-up of synopsis option descriptions Jean-Noël Avila
2025-05-10 12:33 ` [PATCH v3 2/4] git-{var,write-tree} docs: " Jean-Noël Avila
2025-05-10 12:33 ` [PATCH v3 3/4] git-verify-* doc: " Jean-Noël Avila
2025-05-10 12:33 ` [PATCH v3 4/4] git-var doc: fix usage of $ENV_VAR vs ENV_VAR Jean-Noël Avila
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).