* [PATCH 0/3] docs: misc cleanup
@ 2021-02-23 6:39 Denton Liu
2021-02-23 6:39 ` [PATCH 1/3] i18n.txt: camel case and monospace "i18n.commitEncoding" Denton Liu
` (3 more replies)
0 siblings, 4 replies; 21+ messages in thread
From: Denton Liu @ 2021-02-23 6:39 UTC (permalink / raw)
To: Git Mailing List
Just a couple of documentation fixes that I noticed in passing today.
Nothing too controversial.
This branch is based on 'maint'.
Denton Liu (3):
i18n.txt: camel case and monospace "i18n.commitEncoding"
git-cat-file.txt: monospace args and placeholders
git-cat-file.txt: remove references to "sha1"
Documentation/git-cat-file.txt | 52 +++++++++++++++++-----------------
Documentation/i18n.txt | 2 +-
2 files changed, 27 insertions(+), 27 deletions(-)
--
2.30.0.478.g8a0d178c01
^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH 1/3] i18n.txt: camel case and monospace "i18n.commitEncoding"
2021-02-23 6:39 [PATCH 0/3] docs: misc cleanup Denton Liu
@ 2021-02-23 6:39 ` Denton Liu
2021-02-23 19:15 ` Junio C Hamano
2021-02-23 19:26 ` [PATCH v2] " Junio C Hamano
2021-02-23 6:39 ` [PATCH 2/3] git-cat-file.txt: monospace args and placeholders Denton Liu
` (2 subsequent siblings)
3 siblings, 2 replies; 21+ messages in thread
From: Denton Liu @ 2021-02-23 6:39 UTC (permalink / raw)
To: Git Mailing List
In 95791be750 (doc: camelCase the i18n config variables to improve
readability, 2017-07-17), the other i18n config variables were
camel cased. However, this one instance was missed.
Camel case and monospace "i18n.commitEncoding" so that it matches the
surrounding text.
Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
Documentation/i18n.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/i18n.txt b/Documentation/i18n.txt
index 7e36e5b55b..6c6baeeeb7 100644
--- a/Documentation/i18n.txt
+++ b/Documentation/i18n.txt
@@ -38,7 +38,7 @@ mind.
a warning if the commit log message given to it does not look
like a valid UTF-8 string, unless you explicitly say your
project uses a legacy encoding. The way to say this is to
- have i18n.commitencoding in `.git/config` file, like this:
+ have `i18n.commitEncoding` in `.git/config` file, like this:
+
------------
[i18n]
--
2.30.0.478.g8a0d178c01
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [PATCH 2/3] git-cat-file.txt: monospace args and placeholders
2021-02-23 6:39 [PATCH 0/3] docs: misc cleanup Denton Liu
2021-02-23 6:39 ` [PATCH 1/3] i18n.txt: camel case and monospace "i18n.commitEncoding" Denton Liu
@ 2021-02-23 6:39 ` Denton Liu
2021-02-23 6:44 ` Eric Sunshine
2021-02-23 6:59 ` [PATCH v1.1 2/3] git-cat-file.txt: monospace args, placeholders and filenames Denton Liu
2021-02-23 6:39 ` [PATCH 3/3] git-cat-file.txt: remove references to "sha1" Denton Liu
2021-03-03 9:21 ` [PATCH v2 0/2] git-cat-file.txt: doc cleanup Denton Liu
3 siblings, 2 replies; 21+ messages in thread
From: Denton Liu @ 2021-02-23 6:39 UTC (permalink / raw)
To: Git Mailing List
In modern documentation, args and placeholders are monospaced. Format
all remaining args and placeholders as monospace.
Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
Documentation/git-cat-file.txt | 42 +++++++++++++++++-----------------
1 file changed, 21 insertions(+), 21 deletions(-)
diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
index 8e192d87db..987d170506 100644
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.txt
@@ -35,42 +35,42 @@ OPTIONS
-t::
Instead of the content, show the object type identified by
- <object>.
+ `<object>`.
-s::
Instead of the content, show the object size identified by
- <object>.
+ `<object>`.
-e::
- Exit with zero status if <object> exists and is a valid
- object. If <object> is of an invalid format exit with non-zero and
+ Exit with zero status if `<object>` exists and is a valid
+ object. If `<object>` is of an invalid format exit with non-zero and
emits an error on stderr.
-p::
- Pretty-print the contents of <object> based on its type.
+ Pretty-print the contents of `<object>` based on its type.
<type>::
- Typically this matches the real type of <object> but asking
+ Typically this matches the real type of `<object>` but asking
for a type that can trivially be dereferenced from the given
- <object> is also permitted. An example is to ask for a
- "tree" with <object> being a commit object that contains it,
- or to ask for a "blob" with <object> being a tag object that
+ `<object>` is also permitted. An example is to ask for a
+ "tree" with `<object>` being a commit object that contains it,
+ or to ask for a "blob" with `<object>` being a tag object that
points at it.
--textconv::
Show the content as transformed by a textconv filter. In this case,
- <object> has to be of the form <tree-ish>:<path>, or :<path> in
+ `<object>` has to be of the form `<tree-ish>:<path>`, or `:<path>` in
order to apply the filter to the content recorded in the index at
- <path>.
+ `<path>`.
--filters::
Show the content as converted by the filters configured in
- the current working tree for the given <path> (i.e. smudge filters,
- end-of-line conversion, etc). In this case, <object> has to be of
- the form <tree-ish>:<path>, or :<path>.
+ the current working tree for the given `<path>` (i.e. smudge filters,
+ end-of-line conversion, etc). In this case, `<object>` has to be of
+ the form `<tree-ish>:<path>`, or `:<path>`.
--path=<path>::
- For use with --textconv or --filters, to allow specifying an object
+ For use with `--textconv` or `--filters`, to allow specifying an object
name and a path separately, e.g. when it is difficult to figure out
the revision from which the blob came.
@@ -115,7 +115,7 @@ OPTIONS
repository.
--allow-unknown-type::
- Allow -s or -t to query broken/corrupt objects of unknown type.
+ Allow `-s` or `-t` to query broken/corrupt objects of unknown type.
--follow-symlinks::
With --batch or --batch-check, follow symlinks inside the
@@ -175,15 +175,15 @@ respectively print:
OUTPUT
------
-If `-t` is specified, one of the <type>.
+If `-t` is specified, one of the `<type>`.
-If `-s` is specified, the size of the <object> in bytes.
+If `-s` is specified, the size of the `<object>` in bytes.
-If `-e` is specified, no output, unless the <object> is malformed.
+If `-e` is specified, no output, unless the `<object>` is malformed.
-If `-p` is specified, the contents of <object> are pretty-printed.
+If `-p` is specified, the contents of `<object>` are pretty-printed.
-If <type> is specified, the raw (though uncompressed) contents of the <object>
+If `<type>` is specified, the raw (though uncompressed) contents of the `<object>`
will be returned.
BATCH OUTPUT
--
2.30.0.478.g8a0d178c01
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [PATCH 3/3] git-cat-file.txt: remove references to "sha1"
2021-02-23 6:39 [PATCH 0/3] docs: misc cleanup Denton Liu
2021-02-23 6:39 ` [PATCH 1/3] i18n.txt: camel case and monospace "i18n.commitEncoding" Denton Liu
2021-02-23 6:39 ` [PATCH 2/3] git-cat-file.txt: monospace args and placeholders Denton Liu
@ 2021-02-23 6:39 ` Denton Liu
2021-02-23 6:48 ` Eric Sunshine
2021-02-23 7:17 ` [PATCH v2] " Denton Liu
2021-03-03 9:21 ` [PATCH v2 0/2] git-cat-file.txt: doc cleanup Denton Liu
3 siblings, 2 replies; 21+ messages in thread
From: Denton Liu @ 2021-02-23 6:39 UTC (permalink / raw)
To: Git Mailing List
As part of the hash-transition, git can operate on more than just SHA-1
repositories. Replace "sha1"-specific documentation with hash-agnostic
terminology.
Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
Documentation/git-cat-file.txt | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
index 987d170506..ff89c7bfab 100644
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.txt
@@ -200,7 +200,7 @@ object, with placeholders of the form `%(atom)` expanded, followed by a
newline. The available atoms are:
`objectname`::
- The 40-hex object name of the object.
+ The full hex representation of the object.
`objecttype`::
The type of the object (the same as `cat-file -t` reports).
@@ -215,8 +215,8 @@ newline. The available atoms are:
`deltabase`::
If the object is stored as a delta on-disk, this expands to the
- 40-hex sha1 of the delta base object. Otherwise, expands to the
- null sha1 (40 zeroes). See `CAVEATS` below.
+ full hex representation of the delta base object. Otherwise, expands to the
+ null OID (all zeroes). See `CAVEATS` below.
`rest`::
If this atom is used in the output string, input lines are split
@@ -235,14 +235,14 @@ newline.
For example, `--batch` without a custom format would produce:
------------
-<sha1> SP <type> SP <size> LF
+<oid> SP <type> SP <size> LF
<contents> LF
------------
Whereas `--batch-check='%(objectname) %(objecttype)'` would produce:
------------
-<sha1> SP <type> LF
+<oid> SP <type> LF
------------
If a name is specified on stdin that cannot be resolved to an object in
--
2.30.0.478.g8a0d178c01
^ permalink raw reply related [flat|nested] 21+ messages in thread
* Re: [PATCH 2/3] git-cat-file.txt: monospace args and placeholders
2021-02-23 6:39 ` [PATCH 2/3] git-cat-file.txt: monospace args and placeholders Denton Liu
@ 2021-02-23 6:44 ` Eric Sunshine
2021-02-23 6:59 ` [PATCH v1.1 2/3] git-cat-file.txt: monospace args, placeholders and filenames Denton Liu
1 sibling, 0 replies; 21+ messages in thread
From: Eric Sunshine @ 2021-02-23 6:44 UTC (permalink / raw)
To: Denton Liu; +Cc: Git Mailing List
On Tue, Feb 23, 2021 at 1:41 AM Denton Liu <liu.denton@gmail.com> wrote:
> In modern documentation, args and placeholders are monospaced. Format
> all remaining args and placeholders as monospace.
>
> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> ---
> diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
> @@ -115,7 +115,7 @@ OPTIONS
> --allow-unknown-type::
> - Allow -s or -t to query broken/corrupt objects of unknown type.
> + Allow `-s` or `-t` to query broken/corrupt objects of unknown type.
>
> --follow-symlinks::
> With --batch or --batch-check, follow symlinks inside the
Missed these? `--batch`, `--batch-check`
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH 3/3] git-cat-file.txt: remove references to "sha1"
2021-02-23 6:39 ` [PATCH 3/3] git-cat-file.txt: remove references to "sha1" Denton Liu
@ 2021-02-23 6:48 ` Eric Sunshine
2021-02-23 7:17 ` [PATCH v2] " Denton Liu
1 sibling, 0 replies; 21+ messages in thread
From: Eric Sunshine @ 2021-02-23 6:48 UTC (permalink / raw)
To: Denton Liu; +Cc: Git Mailing List
On Tue, Feb 23, 2021 at 1:41 AM Denton Liu <liu.denton@gmail.com> wrote:
> As part of the hash-transition, git can operate on more than just SHA-1
> repositories. Replace "sha1"-specific documentation with hash-agnostic
> terminology.
>
> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> ---
> diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
> @@ -200,7 +200,7 @@ object, with placeholders of the form `%(atom)` expanded, followed by a
> `objectname`::
> - The 40-hex object name of the object.
> + The full hex representation of the object.
I find this new terminology confusing and ambiguous. To me, this seems
to be saying that it is a hex representation of the entire object
rather than a hex representation of the hash of the object. Perhaps
say either "hex representation of the hash of the object" or "hex
representation of the object ID"?
> @@ -215,8 +215,8 @@ newline. The available atoms are:
> `deltabase`::
> If the object is stored as a delta on-disk, this expands to the
> - 40-hex sha1 of the delta base object. Otherwise, expands to the
> - null sha1 (40 zeroes). See `CAVEATS` below.
> + full hex representation of the delta base object. Otherwise, expands to the
> + null OID (all zeroes). See `CAVEATS` below.
Same issue. "hex representation of the delta base object" sounds
misleading. Should probably mention "hash of the" in there somewhere
or something.
^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH v1.1 2/3] git-cat-file.txt: monospace args, placeholders and filenames
2021-02-23 6:39 ` [PATCH 2/3] git-cat-file.txt: monospace args and placeholders Denton Liu
2021-02-23 6:44 ` Eric Sunshine
@ 2021-02-23 6:59 ` Denton Liu
1 sibling, 0 replies; 21+ messages in thread
From: Denton Liu @ 2021-02-23 6:59 UTC (permalink / raw)
To: Git Mailing List; +Cc: Eric Sunshine
In modern documentation, args, placeholders and filenames are
monospaced. Apply monospace formatting to these objects.
Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
Thanks for catching the omission, Eric. I've gone through the
documentation with a fine-tooth comb and caught many more missing
instances.
Documentation/git-cat-file.txt | 56 +++++++++++++++++-----------------
1 file changed, 28 insertions(+), 28 deletions(-)
diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
index 8e192d87db..a1c37a9e81 100644
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.txt
@@ -35,42 +35,42 @@ OPTIONS
-t::
Instead of the content, show the object type identified by
- <object>.
+ `<object>`.
-s::
Instead of the content, show the object size identified by
- <object>.
+ `<object>`.
-e::
- Exit with zero status if <object> exists and is a valid
- object. If <object> is of an invalid format exit with non-zero and
+ Exit with zero status if `<object>` exists and is a valid
+ object. If `<object>` is of an invalid format exit with non-zero and
emits an error on stderr.
-p::
- Pretty-print the contents of <object> based on its type.
+ Pretty-print the contents of `<object>` based on its type.
<type>::
- Typically this matches the real type of <object> but asking
+ Typically this matches the real type of `<object>` but asking
for a type that can trivially be dereferenced from the given
- <object> is also permitted. An example is to ask for a
- "tree" with <object> being a commit object that contains it,
- or to ask for a "blob" with <object> being a tag object that
+ `<object>` is also permitted. An example is to ask for a
+ "tree" with `<object>` being a commit object that contains it,
+ or to ask for a "blob" with `<object>` being a tag object that
points at it.
--textconv::
Show the content as transformed by a textconv filter. In this case,
- <object> has to be of the form <tree-ish>:<path>, or :<path> in
+ `<object>` has to be of the form `<tree-ish>:<path>`, or `:<path>` in
order to apply the filter to the content recorded in the index at
- <path>.
+ `<path>`.
--filters::
Show the content as converted by the filters configured in
- the current working tree for the given <path> (i.e. smudge filters,
- end-of-line conversion, etc). In this case, <object> has to be of
- the form <tree-ish>:<path>, or :<path>.
+ the current working tree for the given `<path>` (i.e. smudge filters,
+ end-of-line conversion, etc). In this case, `<object>` has to be of
+ the form `<tree-ish>:<path>`, or `:<path>`.
--path=<path>::
- For use with --textconv or --filters, to allow specifying an object
+ For use with `--textconv` or `--filters`, to allow specifying an object
name and a path separately, e.g. when it is difficult to figure out
the revision from which the blob came.
@@ -115,15 +115,15 @@ OPTIONS
repository.
--allow-unknown-type::
- Allow -s or -t to query broken/corrupt objects of unknown type.
+ Allow `-s` or `-t` to query broken/corrupt objects of unknown type.
--follow-symlinks::
- With --batch or --batch-check, follow symlinks inside the
+ With `--batch` or `--batch-check`, follow symlinks inside the
repository when requesting objects with extended SHA-1
expressions of the form tree-ish:path-in-tree. Instead of
providing output about the link itself, provide output about
the linked-to object. If a symlink points outside the
- tree-ish (e.g. a link to /foo or a root-level link to ../foo),
+ tree-ish (e.g. a link to `/foo` or a root-level link to `../foo`),
the portion of the link which is outside the tree will be
printed.
+
@@ -175,15 +175,15 @@ respectively print:
OUTPUT
------
-If `-t` is specified, one of the <type>.
+If `-t` is specified, one of the `<type>`.
-If `-s` is specified, the size of the <object> in bytes.
+If `-s` is specified, the size of the `<object>` in bytes.
-If `-e` is specified, no output, unless the <object> is malformed.
+If `-e` is specified, no output, unless the `<object>` is malformed.
-If `-p` is specified, the contents of <object> are pretty-printed.
+If `-p` is specified, the contents of `<object>` are pretty-printed.
-If <type> is specified, the raw (though uncompressed) contents of the <object>
+If `<type>` is specified, the raw (though uncompressed) contents of the `<object>`
will be returned.
BATCH OUTPUT
@@ -258,7 +258,7 @@ If a name is specified that might refer to more than one object (an ambiguous sh
<object> SP ambiguous LF
------------
-If --follow-symlinks is used, and a symlink in the repository points
+If `--follow-symlinks` is used, and a symlink in the repository points
outside the repository, then `cat-file` will ignore any custom format
and print:
@@ -267,11 +267,11 @@ symlink SP <size> LF
<symlink> LF
------------
-The symlink will either be absolute (beginning with a /), or relative
-to the tree root. For instance, if dir/link points to ../../foo, then
-<symlink> will be ../foo. <size> is the size of the symlink in bytes.
+The symlink will either be absolute (beginning with a `/`), or relative
+to the tree root. For instance, if dir/link points to `../../foo`, then
+`<symlink>` will be `../foo`. `<size>` is the size of the symlink in bytes.
-If --follow-symlinks is used, the following error messages will be
+If `--follow-symlinks` is used, the following error messages will be
displayed:
------------
--
2.30.1.823.g0a3b79fd18
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [PATCH v2] git-cat-file.txt: remove references to "sha1"
2021-02-23 6:39 ` [PATCH 3/3] git-cat-file.txt: remove references to "sha1" Denton Liu
2021-02-23 6:48 ` Eric Sunshine
@ 2021-02-23 7:17 ` Denton Liu
2021-02-23 7:48 ` Junio C Hamano
1 sibling, 1 reply; 21+ messages in thread
From: Denton Liu @ 2021-02-23 7:17 UTC (permalink / raw)
To: Git Mailing List; +Cc: Eric Sunshine
As part of the hash-transition, git can operate on more than just SHA-1
repositories. Replace "sha1"-specific documentation with hash-agnostic
terminology.
Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
Documentation/git-cat-file.txt | 11 ++++++-----
1 file changed, 6 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
index a1c37a9e81..c404a9aae8 100644
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.txt
@@ -200,7 +200,7 @@ object, with placeholders of the form `%(atom)` expanded, followed by a
newline. The available atoms are:
`objectname`::
- The 40-hex object name of the object.
+ The full hex representation of the object ID of the object.
`objecttype`::
The type of the object (the same as `cat-file -t` reports).
@@ -215,8 +215,9 @@ newline. The available atoms are:
`deltabase`::
If the object is stored as a delta on-disk, this expands to the
- 40-hex sha1 of the delta base object. Otherwise, expands to the
- null sha1 (40 zeroes). See `CAVEATS` below.
+ full hex representation of the object ID of the delta base
+ object. Otherwise, expands to the null OID (all zeroes). See
+ `CAVEATS` below.
`rest`::
If this atom is used in the output string, input lines are split
@@ -235,14 +236,14 @@ newline.
For example, `--batch` without a custom format would produce:
------------
-<sha1> SP <type> SP <size> LF
+<oid> SP <type> SP <size> LF
<contents> LF
------------
Whereas `--batch-check='%(objectname) %(objecttype)'` would produce:
------------
-<sha1> SP <type> LF
+<oid> SP <type> LF
------------
If a name is specified on stdin that cannot be resolved to an object in
--
2.30.1.823.g0a3b79fd18
^ permalink raw reply related [flat|nested] 21+ messages in thread
* Re: [PATCH v2] git-cat-file.txt: remove references to "sha1"
2021-02-23 7:17 ` [PATCH v2] " Denton Liu
@ 2021-02-23 7:48 ` Junio C Hamano
0 siblings, 0 replies; 21+ messages in thread
From: Junio C Hamano @ 2021-02-23 7:48 UTC (permalink / raw)
To: Denton Liu; +Cc: Git Mailing List, Eric Sunshine
Denton Liu <liu.denton@gmail.com> writes:
> `objectname`::
> - The 40-hex object name of the object.
> + The full hex representation of the object ID of the object.
While I agree that it is a good idea to move away from an explicit
mention of "40", I do not see why we would want to explain "object
name" not as "object name" but as "object ID". IOW, s/ID/name/.
> @@ -215,8 +215,9 @@ newline. The available atoms are:
>
> `deltabase`::
> If the object is stored as a delta on-disk, this expands to the
> - 40-hex sha1 of the delta base object. Otherwise, expands to the
> - null sha1 (40 zeroes). See `CAVEATS` below.
> + full hex representation of the object ID of the delta base
> + object. Otherwise, expands to the null OID (all zeroes). See
> + `CAVEATS` below.
Likewise. Documentation/glossary-content.txt says "object name" is
the canonical term, with "object identifier", "hash" etc. as its
synonyms.
> @@ -235,14 +236,14 @@ newline.
> For example, `--batch` without a custom format would produce:
>
> ------------
> -<sha1> SP <type> SP <size> LF
> +<oid> SP <type> SP <size> LF
> <contents> LF
> ------------
>
> Whereas `--batch-check='%(objectname) %(objecttype)'` would produce:
>
> ------------
> -<sha1> SP <type> LF
> +<oid> SP <type> LF
> ------------
These look good.
Thanks.
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH 1/3] i18n.txt: camel case and monospace "i18n.commitEncoding"
2021-02-23 6:39 ` [PATCH 1/3] i18n.txt: camel case and monospace "i18n.commitEncoding" Denton Liu
@ 2021-02-23 19:15 ` Junio C Hamano
2021-02-23 19:26 ` [PATCH v2] " Junio C Hamano
1 sibling, 0 replies; 21+ messages in thread
From: Junio C Hamano @ 2021-02-23 19:15 UTC (permalink / raw)
To: Denton Liu; +Cc: Git Mailing List
Denton Liu <liu.denton@gmail.com> writes:
> In 95791be750 (doc: camelCase the i18n config variables to improve
> readability, 2017-07-17), the other i18n config variables were
> camel cased. However, this one instance was missed.
>
> Camel case and monospace "i18n.commitEncoding" so that it matches the
> surrounding text.
>
> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> ---
> Documentation/i18n.txt | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
Looking good.
> diff --git a/Documentation/i18n.txt b/Documentation/i18n.txt
> index 7e36e5b55b..6c6baeeeb7 100644
> --- a/Documentation/i18n.txt
> +++ b/Documentation/i18n.txt
> @@ -38,7 +38,7 @@ mind.
> a warning if the commit log message given to it does not look
> like a valid UTF-8 string, unless you explicitly say your
> project uses a legacy encoding. The way to say this is to
> - have i18n.commitencoding in `.git/config` file, like this:
> + have `i18n.commitEncoding` in `.git/config` file, like this:
> +
> ------------
> [i18n]
Thanks, but whenever you noticed an issue like "Ah, here we used an
incorrect spelling i18n.commitencoding", please make it a habit to
see if we did exactly the same mistake elsewhere (you have been
working with Git long enough to know how cheap such a check is):
$ git grep -F -e i18n.commitencoding -- \
Documentation/ ':!Documentation/RelNotes/'
and you would have found three other instances.
This obviously does not have to be part of this miniseries, but I
wonder if we should have a list of all the configuration variables
in one place that we can use to record the canonical spelling of
these variables. As
$ git grep -h -E -i \
-e '^[a-z][-a-z0-9]*\.[a-z][-a-z0-9]*::' \
-e '^[a-z][-a-z0-9]*\.(\*|<?[a-z][-a-z0-9]*>?)\.(\*|<?[a-z][-a-z0-9]*>?)::' \
Documentation/config
gives many hits with camelCased names, it might be a good place to
start.
Pretending that the above gives a good "canonical list" (it does not
yet, if you look at the hits), I got curious how far we can go.
Massaging the output from the above into config-variables.lst
$ ... above command ... |
sed -e 's/::$//' |
sort -u >config-variables.lst
and then to extract use of these tokens in the main part of the
documentation like this:
$ git grep -h -o -i -F -f config-variables.lst -- \
Documentation/ ':!Documentation/RelNotes/' |
sort -u >config-usage.lst
gives us something we can compare with the "canonical" usage list.
$ comm -3 config-usage.lst config-variables.lst
blame.blankboundary
core.excludesfile
core.filemode
core.gitproxy
core.ignorestat
core.logallrefupdates
core.repositoryformatversion
core.trustCtime
http.sslverify
http.sslversion
i18n.commitencoding
push.pushoption
remote.<name>.partialCloneFilter
remote.pushdefault
repack.UseDeltaBaseOffset
sendemail.aliasesfile
showbranch.default
transfer.hiderefs
uploadArchive.allowUnreachable
Some of them may be false hits, some may be showing that the copy in
Documentation/config/ are spelled in all lowercase, but the majority
of the hits above seem to be genuine errors similar to what you fixed
in your patch.
Thanks.
^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH v2] i18n.txt: camel case and monospace "i18n.commitEncoding"
2021-02-23 6:39 ` [PATCH 1/3] i18n.txt: camel case and monospace "i18n.commitEncoding" Denton Liu
2021-02-23 19:15 ` Junio C Hamano
@ 2021-02-23 19:26 ` Junio C Hamano
2021-02-23 19:32 ` Eric Sunshine
1 sibling, 1 reply; 21+ messages in thread
From: Junio C Hamano @ 2021-02-23 19:26 UTC (permalink / raw)
To: Denton Liu; +Cc: Git Mailing List
In 95791be750 (doc: camelCase the i18n config variables to improve
readability, 2017-07-17), the other i18n config variables were
camel cased. However, this one instance was missed.
Camel case and monospace "i18n.commitEncoding" so that it matches the
surrounding text.
Signed-off-by: Denton Liu <liu.denton@gmail.com>
[jc: fixed 3 other mistakes that are exactly the same]
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
* So, while I still remember, I amended your commit and queued
this.
Documentation/git-am.txt | 2 +-
Documentation/git-mailinfo.txt | 4 ++--
Documentation/i18n.txt | 2 +-
3 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 06bc063542..decd8ae122 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -79,7 +79,7 @@ OPTIONS
Pass `-u` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
The proposed commit log message taken from the e-mail
is re-coded into UTF-8 encoding (configuration variable
- `i18n.commitencoding` can be used to specify project's
+ `i18n.commitEncoding` can be used to specify project's
preferred encoding if it is not UTF-8).
+
This was optional in prior versions of git, but now it is the
diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt
index 7a6aed0e30..d343f040f5 100644
--- a/Documentation/git-mailinfo.txt
+++ b/Documentation/git-mailinfo.txt
@@ -53,7 +53,7 @@ character.
The commit log message, author name and author email are
taken from the e-mail, and after minimally decoding MIME
transfer encoding, re-coded in the charset specified by
- i18n.commitencoding (defaulting to UTF-8) by transliterating
+ `i18n.commitEncoding` (defaulting to UTF-8) by transliterating
them. This used to be optional but now it is the default.
+
Note that the patch is always used as-is without charset
@@ -61,7 +61,7 @@ conversion, even with this flag.
--encoding=<encoding>::
Similar to -u. But when re-coding, the charset specified here is
- used instead of the one specified by i18n.commitencoding or UTF-8.
+ used instead of the one specified by `i18n.commitEncoding` or UTF-8.
-n::
Disable all charset re-coding of the metadata.
diff --git a/Documentation/i18n.txt b/Documentation/i18n.txt
index 7e36e5b55b..6c6baeeeb7 100644
--- a/Documentation/i18n.txt
+++ b/Documentation/i18n.txt
@@ -38,7 +38,7 @@ mind.
a warning if the commit log message given to it does not look
like a valid UTF-8 string, unless you explicitly say your
project uses a legacy encoding. The way to say this is to
- have i18n.commitencoding in `.git/config` file, like this:
+ have `i18n.commitEncoding` in `.git/config` file, like this:
+
------------
[i18n]
--
2.30.1-808-g8fd60da8ea
^ permalink raw reply related [flat|nested] 21+ messages in thread
* Re: [PATCH v2] i18n.txt: camel case and monospace "i18n.commitEncoding"
2021-02-23 19:26 ` [PATCH v2] " Junio C Hamano
@ 2021-02-23 19:32 ` Eric Sunshine
2021-02-23 19:41 ` Junio C Hamano
0 siblings, 1 reply; 21+ messages in thread
From: Eric Sunshine @ 2021-02-23 19:32 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Denton Liu, Git Mailing List
On Tue, Feb 23, 2021 at 2:28 PM Junio C Hamano <gitster@pobox.com> wrote:
> In 95791be750 (doc: camelCase the i18n config variables to improve
> readability, 2017-07-17), the other i18n config variables were
> camel cased. However, this one instance was missed.
>
> Camel case and monospace "i18n.commitEncoding" so that it matches the
> surrounding text.
>
> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> [jc: fixed 3 other mistakes that are exactly the same]
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> * So, while I still remember, I amended your commit and queued
> this.
Denton's authorship seems to have been lost (no From: header). Was
that intentional?
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v2] i18n.txt: camel case and monospace "i18n.commitEncoding"
2021-02-23 19:32 ` Eric Sunshine
@ 2021-02-23 19:41 ` Junio C Hamano
2021-02-24 20:26 ` [PATCH v3 0/3] doc: spell configuration variable names in camelCase Junio C Hamano
0 siblings, 1 reply; 21+ messages in thread
From: Junio C Hamano @ 2021-02-23 19:41 UTC (permalink / raw)
To: Eric Sunshine; +Cc: Denton Liu, Git Mailing List
Eric Sunshine <sunshine@sunshineco.com> writes:
> On Tue, Feb 23, 2021 at 2:28 PM Junio C Hamano <gitster@pobox.com> wrote:
>> In 95791be750 (doc: camelCase the i18n config variables to improve
>> readability, 2017-07-17), the other i18n config variables were
>> camel cased. However, this one instance was missed.
>>
>> Camel case and monospace "i18n.commitEncoding" so that it matches the
>> surrounding text.
>>
>> Signed-off-by: Denton Liu <liu.denton@gmail.com>
>> [jc: fixed 3 other mistakes that are exactly the same]
>> Signed-off-by: Junio C Hamano <gitster@pobox.com>
>> ---
>> * So, while I still remember, I amended your commit and queued
>> this.
>
> Denton's authorship seems to have been lost (no From: header). Was
> that intentional?
I didn't even notice.
I actually expect that Denton will produce a more complete series
based on the "comm -3" output, so that this patch itself (or its
authorship) won't matter ;-)
And I also expect that somebody will take the "two greps and comm"
trick I showed and wrap it into some form of doc-lint. Hint, hint...
Thanks.
^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH v3 0/3] doc: spell configuration variable names in camelCase
2021-02-23 19:41 ` Junio C Hamano
@ 2021-02-24 20:26 ` Junio C Hamano
2021-02-24 20:26 ` [PATCH v3 1/3] i18n.txt: camel case and monospace "i18n.commitEncoding" Junio C Hamano
` (2 more replies)
0 siblings, 3 replies; 21+ messages in thread
From: Junio C Hamano @ 2021-02-24 20:26 UTC (permalink / raw)
To: git
I said in the first review on Denton's patch
This obviously does not have to be part of this miniseries, but I
wonder if we should have a list of all the configuration variables
in one place that we can use to record the canonical spelling of
these variables. As
$ git grep -h -E -i \
-e '^[a-z][-a-z0-9]*\.[a-z][-a-z0-9]*::' \
-e '^[a-z][-a-z0-9]*\.(\*|<?[a-z][-a-z0-9]*>?)\.(\*|<?[a-z][-a-z0-9]*>?)::' \
Documentation/config
gives many hits with camelCased names, it might be a good place to
start.
Pretending that the above gives a good "canonical list" (it does not
yet, if you look at the hits), I got curious how far we can go.
Massaging the output from the above into config-variables.lst
$ ... above command ... |
sed -e 's/::$//' |
sort -u >config-variables.lst
and then to extract use of these tokens in the main part of the
documentation like this:
$ git grep -h -o -i -F -f config-variables.lst -- \
Documentation/ ':!Documentation/RelNotes/' |
sort -u >config-usage.lst
gives us something we can compare with the "canonical" usage list.
$ comm -3 config-usage.lst config-variables.lst
blame.blankboundary
core.excludesfile
core.filemode
core.gitproxy
core.ignorestat
core.logallrefupdates
core.repositoryformatversion
core.trustCtime
http.sslverify
http.sslversion
i18n.commitencoding
push.pushoption
remote.<name>.partialCloneFilter
remote.pushdefault
repack.UseDeltaBaseOffset
sendemail.aliasesfile
showbranch.default
transfer.hiderefs
uploadArchive.allowUnreachable
Some of them may be false hits, some may be showing that the copy in
Documentation/config/ are spelled in all lowercase, but the majority
of the hits above seem to be genuine errors similar to what you fixed
in your patch.
Thanks.
and as I identified a handful of low hanging fruits that way, here
are a few patches on top of his patch that started the whole thing.
I think we should make sure Documentation/config/*.txt
- spells all the configuration variables in the way we want to see
them, and
- covers all the configuration variables.
before we can proceed with more low hanging fruits with confidence,
as I do think the coverage is very good, but I know it is not 100%,
and the eventual goal should be to make sure we can teach lint-docs
to catch these before the reviewers even see them.
Denton Liu (1):
i18n.txt: camel case and monospace "i18n.commitEncoding"
Junio C Hamano (2):
blame-options.txt: camelcase blame.blankBoundary
index-format doc: camelCase core.excludesFile
Documentation/blame-options.txt | 2 +-
Documentation/git-am.txt | 2 +-
Documentation/git-mailinfo.txt | 4 ++--
Documentation/i18n.txt | 2 +-
Documentation/technical/index-format.txt | 4 ++--
5 files changed, 7 insertions(+), 7 deletions(-)
--
2.30.1-826-g07a034c5ea
^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH v3 1/3] i18n.txt: camel case and monospace "i18n.commitEncoding"
2021-02-24 20:26 ` [PATCH v3 0/3] doc: spell configuration variable names in camelCase Junio C Hamano
@ 2021-02-24 20:26 ` Junio C Hamano
2021-02-24 20:26 ` [PATCH v3 2/3] blame-options.txt: camelcase blame.blankBoundary Junio C Hamano
2021-02-24 20:26 ` [PATCH v3 3/3] index-format doc: camelCase core.excludesFile Junio C Hamano
2 siblings, 0 replies; 21+ messages in thread
From: Junio C Hamano @ 2021-02-24 20:26 UTC (permalink / raw)
To: git; +Cc: Denton Liu
From: Denton Liu <liu.denton@gmail.com>
In 95791be750 (doc: camelCase the i18n config variables to improve
readability, 2017-07-17), the other i18n config variables were
camel cased. However, this one instance was missed.
Camel case and monospace "i18n.commitEncoding" so that it matches the
surrounding text.
Signed-off-by: Denton Liu <liu.denton@gmail.com>
[jc: fixed 3 other mistakes that are exactly the same]
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
Documentation/git-am.txt | 2 +-
Documentation/git-mailinfo.txt | 4 ++--
Documentation/i18n.txt | 2 +-
3 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 06bc063542..decd8ae122 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -79,7 +79,7 @@ OPTIONS
Pass `-u` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
The proposed commit log message taken from the e-mail
is re-coded into UTF-8 encoding (configuration variable
- `i18n.commitencoding` can be used to specify project's
+ `i18n.commitEncoding` can be used to specify project's
preferred encoding if it is not UTF-8).
+
This was optional in prior versions of git, but now it is the
diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt
index 7a6aed0e30..d343f040f5 100644
--- a/Documentation/git-mailinfo.txt
+++ b/Documentation/git-mailinfo.txt
@@ -53,7 +53,7 @@ character.
The commit log message, author name and author email are
taken from the e-mail, and after minimally decoding MIME
transfer encoding, re-coded in the charset specified by
- i18n.commitencoding (defaulting to UTF-8) by transliterating
+ `i18n.commitEncoding` (defaulting to UTF-8) by transliterating
them. This used to be optional but now it is the default.
+
Note that the patch is always used as-is without charset
@@ -61,7 +61,7 @@ conversion, even with this flag.
--encoding=<encoding>::
Similar to -u. But when re-coding, the charset specified here is
- used instead of the one specified by i18n.commitencoding or UTF-8.
+ used instead of the one specified by `i18n.commitEncoding` or UTF-8.
-n::
Disable all charset re-coding of the metadata.
diff --git a/Documentation/i18n.txt b/Documentation/i18n.txt
index 7e36e5b55b..6c6baeeeb7 100644
--- a/Documentation/i18n.txt
+++ b/Documentation/i18n.txt
@@ -38,7 +38,7 @@ mind.
a warning if the commit log message given to it does not look
like a valid UTF-8 string, unless you explicitly say your
project uses a legacy encoding. The way to say this is to
- have i18n.commitencoding in `.git/config` file, like this:
+ have `i18n.commitEncoding` in `.git/config` file, like this:
+
------------
[i18n]
--
2.30.1-826-g07a034c5ea
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [PATCH v3 2/3] blame-options.txt: camelcase blame.blankBoundary
2021-02-24 20:26 ` [PATCH v3 0/3] doc: spell configuration variable names in camelCase Junio C Hamano
2021-02-24 20:26 ` [PATCH v3 1/3] i18n.txt: camel case and monospace "i18n.commitEncoding" Junio C Hamano
@ 2021-02-24 20:26 ` Junio C Hamano
2021-02-24 20:26 ` [PATCH v3 3/3] index-format doc: camelCase core.excludesFile Junio C Hamano
2 siblings, 0 replies; 21+ messages in thread
From: Junio C Hamano @ 2021-02-24 20:26 UTC (permalink / raw)
To: git
All other references to blame.* configuration variables are
camelCased already. Update this one to match.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
Documentation/blame-options.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt
index dc3bceb6d1..117f4cf806 100644
--- a/Documentation/blame-options.txt
+++ b/Documentation/blame-options.txt
@@ -1,6 +1,6 @@
-b::
Show blank SHA-1 for boundary commits. This can also
- be controlled via the `blame.blankboundary` config option.
+ be controlled via the `blame.blankBoundary` config option.
--root::
Do not treat root commits as boundaries. This can also be
--
2.30.1-826-g07a034c5ea
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [PATCH v3 3/3] index-format doc: camelCase core.excludesFile
2021-02-24 20:26 ` [PATCH v3 0/3] doc: spell configuration variable names in camelCase Junio C Hamano
2021-02-24 20:26 ` [PATCH v3 1/3] i18n.txt: camel case and monospace "i18n.commitEncoding" Junio C Hamano
2021-02-24 20:26 ` [PATCH v3 2/3] blame-options.txt: camelcase blame.blankBoundary Junio C Hamano
@ 2021-02-24 20:26 ` Junio C Hamano
2 siblings, 0 replies; 21+ messages in thread
From: Junio C Hamano @ 2021-02-24 20:26 UTC (permalink / raw)
To: git
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
Documentation/technical/index-format.txt | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt
index 69edf46c03..8af608055f 100644
--- a/Documentation/technical/index-format.txt
+++ b/Documentation/technical/index-format.txt
@@ -251,14 +251,14 @@ Git index format
- Stat data of $GIT_DIR/info/exclude. See "Index entry" section from
ctime field until "file size".
- - Stat data of core.excludesfile
+ - Stat data of core.excludesFile
- 32-bit dir_flags (see struct dir_struct)
- Hash of $GIT_DIR/info/exclude. A null hash means the file
does not exist.
- - Hash of core.excludesfile. A null hash means the file does
+ - Hash of core.excludesFile. A null hash means the file does
not exist.
- NUL-terminated string of per-dir exclude file name. This usually
--
2.30.1-826-g07a034c5ea
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [PATCH v2 0/2] git-cat-file.txt: doc cleanup
2021-02-23 6:39 [PATCH 0/3] docs: misc cleanup Denton Liu
` (2 preceding siblings ...)
2021-02-23 6:39 ` [PATCH 3/3] git-cat-file.txt: remove references to "sha1" Denton Liu
@ 2021-03-03 9:21 ` Denton Liu
2021-03-03 9:21 ` [PATCH v2 1/2] git-cat-file.txt: monospace args, placeholders and filenames Denton Liu
` (2 more replies)
3 siblings, 3 replies; 21+ messages in thread
From: Denton Liu @ 2021-03-03 9:21 UTC (permalink / raw)
To: Git Mailing List; +Cc: Eric Sunshine, Junio C Hamano
A couple of fixes that I've noticed in passing.
Changes since v1:
* Drop 'i18n.txt: camel case and monospace "i18n.commitEncoding"' (it's already
merged to 'master')
* Change "object ID of the object" to "object name"
Denton Liu (2):
git-cat-file.txt: monospace args, placeholders and filenames
git-cat-file.txt: remove references to "sha1"
Documentation/git-cat-file.txt | 67 +++++++++++++++++-----------------
1 file changed, 34 insertions(+), 33 deletions(-)
Range-diff against v1:
1: cc48b12516 < -: ---------- i18n.txt: camel case and monospace "i18n.commitEncoding"
2: 7dab69ce23 = 1: 6d044cf540 git-cat-file.txt: monospace args, placeholders and filenames
3: 4030a678b9 ! 2: 1b57fdad97 git-cat-file.txt: remove references to "sha1"
@@ Documentation/git-cat-file.txt: object, with placeholders of the form `%(atom)`
`objectname`::
- The 40-hex object name of the object.
-+ The full hex representation of the object ID of the object.
++ The full hex representation of the object name.
`objecttype`::
The type of the object (the same as `cat-file -t` reports).
@@ Documentation/git-cat-file.txt: newline. The available atoms are:
If the object is stored as a delta on-disk, this expands to the
- 40-hex sha1 of the delta base object. Otherwise, expands to the
- null sha1 (40 zeroes). See `CAVEATS` below.
-+ full hex representation of the object ID of the delta base
-+ object. Otherwise, expands to the null OID (all zeroes). See
-+ `CAVEATS` below.
++ full hex representation of the delta base object name.
++ Otherwise, expands to the null OID (all zeroes). See `CAVEATS`
++ below.
`rest`::
If this atom is used in the output string, input lines are split
--
2.30.1.823.g0a3b79fd18
^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH v2 1/2] git-cat-file.txt: monospace args, placeholders and filenames
2021-03-03 9:21 ` [PATCH v2 0/2] git-cat-file.txt: doc cleanup Denton Liu
@ 2021-03-03 9:21 ` Denton Liu
2021-03-03 9:21 ` [PATCH v2 2/2] git-cat-file.txt: remove references to "sha1" Denton Liu
2021-03-04 0:43 ` [PATCH v2 0/2] git-cat-file.txt: doc cleanup Junio C Hamano
2 siblings, 0 replies; 21+ messages in thread
From: Denton Liu @ 2021-03-03 9:21 UTC (permalink / raw)
To: Git Mailing List; +Cc: Eric Sunshine, Junio C Hamano
In modern documentation, args, placeholders and filenames are
monospaced. Apply monospace formatting to these objects.
Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
Documentation/git-cat-file.txt | 56 +++++++++++++++++-----------------
1 file changed, 28 insertions(+), 28 deletions(-)
diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
index 8e192d87db..a1c37a9e81 100644
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.txt
@@ -35,42 +35,42 @@ OPTIONS
-t::
Instead of the content, show the object type identified by
- <object>.
+ `<object>`.
-s::
Instead of the content, show the object size identified by
- <object>.
+ `<object>`.
-e::
- Exit with zero status if <object> exists and is a valid
- object. If <object> is of an invalid format exit with non-zero and
+ Exit with zero status if `<object>` exists and is a valid
+ object. If `<object>` is of an invalid format exit with non-zero and
emits an error on stderr.
-p::
- Pretty-print the contents of <object> based on its type.
+ Pretty-print the contents of `<object>` based on its type.
<type>::
- Typically this matches the real type of <object> but asking
+ Typically this matches the real type of `<object>` but asking
for a type that can trivially be dereferenced from the given
- <object> is also permitted. An example is to ask for a
- "tree" with <object> being a commit object that contains it,
- or to ask for a "blob" with <object> being a tag object that
+ `<object>` is also permitted. An example is to ask for a
+ "tree" with `<object>` being a commit object that contains it,
+ or to ask for a "blob" with `<object>` being a tag object that
points at it.
--textconv::
Show the content as transformed by a textconv filter. In this case,
- <object> has to be of the form <tree-ish>:<path>, or :<path> in
+ `<object>` has to be of the form `<tree-ish>:<path>`, or `:<path>` in
order to apply the filter to the content recorded in the index at
- <path>.
+ `<path>`.
--filters::
Show the content as converted by the filters configured in
- the current working tree for the given <path> (i.e. smudge filters,
- end-of-line conversion, etc). In this case, <object> has to be of
- the form <tree-ish>:<path>, or :<path>.
+ the current working tree for the given `<path>` (i.e. smudge filters,
+ end-of-line conversion, etc). In this case, `<object>` has to be of
+ the form `<tree-ish>:<path>`, or `:<path>`.
--path=<path>::
- For use with --textconv or --filters, to allow specifying an object
+ For use with `--textconv` or `--filters`, to allow specifying an object
name and a path separately, e.g. when it is difficult to figure out
the revision from which the blob came.
@@ -115,15 +115,15 @@ OPTIONS
repository.
--allow-unknown-type::
- Allow -s or -t to query broken/corrupt objects of unknown type.
+ Allow `-s` or `-t` to query broken/corrupt objects of unknown type.
--follow-symlinks::
- With --batch or --batch-check, follow symlinks inside the
+ With `--batch` or `--batch-check`, follow symlinks inside the
repository when requesting objects with extended SHA-1
expressions of the form tree-ish:path-in-tree. Instead of
providing output about the link itself, provide output about
the linked-to object. If a symlink points outside the
- tree-ish (e.g. a link to /foo or a root-level link to ../foo),
+ tree-ish (e.g. a link to `/foo` or a root-level link to `../foo`),
the portion of the link which is outside the tree will be
printed.
+
@@ -175,15 +175,15 @@ respectively print:
OUTPUT
------
-If `-t` is specified, one of the <type>.
+If `-t` is specified, one of the `<type>`.
-If `-s` is specified, the size of the <object> in bytes.
+If `-s` is specified, the size of the `<object>` in bytes.
-If `-e` is specified, no output, unless the <object> is malformed.
+If `-e` is specified, no output, unless the `<object>` is malformed.
-If `-p` is specified, the contents of <object> are pretty-printed.
+If `-p` is specified, the contents of `<object>` are pretty-printed.
-If <type> is specified, the raw (though uncompressed) contents of the <object>
+If `<type>` is specified, the raw (though uncompressed) contents of the `<object>`
will be returned.
BATCH OUTPUT
@@ -258,7 +258,7 @@ If a name is specified that might refer to more than one object (an ambiguous sh
<object> SP ambiguous LF
------------
-If --follow-symlinks is used, and a symlink in the repository points
+If `--follow-symlinks` is used, and a symlink in the repository points
outside the repository, then `cat-file` will ignore any custom format
and print:
@@ -267,11 +267,11 @@ symlink SP <size> LF
<symlink> LF
------------
-The symlink will either be absolute (beginning with a /), or relative
-to the tree root. For instance, if dir/link points to ../../foo, then
-<symlink> will be ../foo. <size> is the size of the symlink in bytes.
+The symlink will either be absolute (beginning with a `/`), or relative
+to the tree root. For instance, if dir/link points to `../../foo`, then
+`<symlink>` will be `../foo`. `<size>` is the size of the symlink in bytes.
-If --follow-symlinks is used, the following error messages will be
+If `--follow-symlinks` is used, the following error messages will be
displayed:
------------
--
2.30.1.823.g0a3b79fd18
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [PATCH v2 2/2] git-cat-file.txt: remove references to "sha1"
2021-03-03 9:21 ` [PATCH v2 0/2] git-cat-file.txt: doc cleanup Denton Liu
2021-03-03 9:21 ` [PATCH v2 1/2] git-cat-file.txt: monospace args, placeholders and filenames Denton Liu
@ 2021-03-03 9:21 ` Denton Liu
2021-03-04 0:43 ` [PATCH v2 0/2] git-cat-file.txt: doc cleanup Junio C Hamano
2 siblings, 0 replies; 21+ messages in thread
From: Denton Liu @ 2021-03-03 9:21 UTC (permalink / raw)
To: Git Mailing List; +Cc: Eric Sunshine, Junio C Hamano
As part of the hash-transition, git can operate on more than just SHA-1
repositories. Replace "sha1"-specific documentation with hash-agnostic
terminology.
Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
Documentation/git-cat-file.txt | 11 ++++++-----
1 file changed, 6 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
index a1c37a9e81..4eb0421b3f 100644
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.txt
@@ -200,7 +200,7 @@ object, with placeholders of the form `%(atom)` expanded, followed by a
newline. The available atoms are:
`objectname`::
- The 40-hex object name of the object.
+ The full hex representation of the object name.
`objecttype`::
The type of the object (the same as `cat-file -t` reports).
@@ -215,8 +215,9 @@ newline. The available atoms are:
`deltabase`::
If the object is stored as a delta on-disk, this expands to the
- 40-hex sha1 of the delta base object. Otherwise, expands to the
- null sha1 (40 zeroes). See `CAVEATS` below.
+ full hex representation of the delta base object name.
+ Otherwise, expands to the null OID (all zeroes). See `CAVEATS`
+ below.
`rest`::
If this atom is used in the output string, input lines are split
@@ -235,14 +236,14 @@ newline.
For example, `--batch` without a custom format would produce:
------------
-<sha1> SP <type> SP <size> LF
+<oid> SP <type> SP <size> LF
<contents> LF
------------
Whereas `--batch-check='%(objectname) %(objecttype)'` would produce:
------------
-<sha1> SP <type> LF
+<oid> SP <type> LF
------------
If a name is specified on stdin that cannot be resolved to an object in
--
2.30.1.823.g0a3b79fd18
^ permalink raw reply related [flat|nested] 21+ messages in thread
* Re: [PATCH v2 0/2] git-cat-file.txt: doc cleanup
2021-03-03 9:21 ` [PATCH v2 0/2] git-cat-file.txt: doc cleanup Denton Liu
2021-03-03 9:21 ` [PATCH v2 1/2] git-cat-file.txt: monospace args, placeholders and filenames Denton Liu
2021-03-03 9:21 ` [PATCH v2 2/2] git-cat-file.txt: remove references to "sha1" Denton Liu
@ 2021-03-04 0:43 ` Junio C Hamano
2 siblings, 0 replies; 21+ messages in thread
From: Junio C Hamano @ 2021-03-04 0:43 UTC (permalink / raw)
To: Denton Liu; +Cc: Git Mailing List, Eric Sunshine
Denton Liu <liu.denton@gmail.com> writes:
> Denton Liu (2):
> git-cat-file.txt: monospace args, placeholders and filenames
> git-cat-file.txt: remove references to "sha1"
Thanks, will queue.
^ permalink raw reply [flat|nested] 21+ messages in thread
end of thread, other threads:[~2021-03-04 1:11 UTC | newest]
Thread overview: 21+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-02-23 6:39 [PATCH 0/3] docs: misc cleanup Denton Liu
2021-02-23 6:39 ` [PATCH 1/3] i18n.txt: camel case and monospace "i18n.commitEncoding" Denton Liu
2021-02-23 19:15 ` Junio C Hamano
2021-02-23 19:26 ` [PATCH v2] " Junio C Hamano
2021-02-23 19:32 ` Eric Sunshine
2021-02-23 19:41 ` Junio C Hamano
2021-02-24 20:26 ` [PATCH v3 0/3] doc: spell configuration variable names in camelCase Junio C Hamano
2021-02-24 20:26 ` [PATCH v3 1/3] i18n.txt: camel case and monospace "i18n.commitEncoding" Junio C Hamano
2021-02-24 20:26 ` [PATCH v3 2/3] blame-options.txt: camelcase blame.blankBoundary Junio C Hamano
2021-02-24 20:26 ` [PATCH v3 3/3] index-format doc: camelCase core.excludesFile Junio C Hamano
2021-02-23 6:39 ` [PATCH 2/3] git-cat-file.txt: monospace args and placeholders Denton Liu
2021-02-23 6:44 ` Eric Sunshine
2021-02-23 6:59 ` [PATCH v1.1 2/3] git-cat-file.txt: monospace args, placeholders and filenames Denton Liu
2021-02-23 6:39 ` [PATCH 3/3] git-cat-file.txt: remove references to "sha1" Denton Liu
2021-02-23 6:48 ` Eric Sunshine
2021-02-23 7:17 ` [PATCH v2] " Denton Liu
2021-02-23 7:48 ` Junio C Hamano
2021-03-03 9:21 ` [PATCH v2 0/2] git-cat-file.txt: doc cleanup Denton Liu
2021-03-03 9:21 ` [PATCH v2 1/2] git-cat-file.txt: monospace args, placeholders and filenames Denton Liu
2021-03-03 9:21 ` [PATCH v2 2/2] git-cat-file.txt: remove references to "sha1" Denton Liu
2021-03-04 0:43 ` [PATCH v2 0/2] git-cat-file.txt: doc cleanup Junio C Hamano
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
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 read-only IMAP folder(s) and NNTP newsgroup(s).