Skip to contentSkip to conversation

docs: misc cleanup

PATCH In review Denton Liu 3 participants 21 messages Feb 23, 2021 – Mar 4, 2021 Documentation

lore
Share & tools
lore

Denton Liu

author
#0 lore raw

cover docs: misc cleanup

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(-)
Signature · 1 line
2.30.0.478.g8a0d178c01
author
#1 lore raw

PATCH 1/3 i18n.txt: camel case and monospace "i18n.commitEncoding"

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.

---
 Documentation/i18n.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/i18n.txt +1 -1
index 7e36e5b55b..6c6baeeeb7 100644
@@ -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]
Signature · 1 line
2.30.0.478.g8a0d178c01
#2 lore raw

Re: [PATCH 1/3] i18n.txt: camel case and monospace "i18n.commitEncoding"

Quoted 11 lines · Denton Liu

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.

---
 Documentation/i18n.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Looking good.

Documentation/i18n.txt mind. · line 44

Quoted 13 lines
Documentation/i18n.txt +1 -1
index 7e36e5b55b..6c6baeeeb7 100644
@@ -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.

#3 lore raw

PATCH v2 1/1 i18n.txt: camel case and monospace "i18n.commitEncoding"

In reply to Denton Liu

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.

[jc: fixed 3 other mistakes that are exactly the same]

---

* 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(-)
Documentation/git-am.txt +1 -1
index 06bc063542..decd8ae122 100644
@@ -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
Documentation/git-mailinfo.txt +2 -2
index 7a6aed0e30..d343f040f5 100644
@@ -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.
Documentation/i18n.txt +1 -1
index 7e36e5b55b..6c6baeeeb7 100644
@@ -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]
Signature · 1 line
2.30.1-808-g8fd60da8ea
#4 lore raw

Re: [PATCH v2] i18n.txt: camel case and monospace "i18n.commitEncoding"

Quoted 7 lines · Junio C Hamano

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.

Quoted 6 lines
[jc: fixed 3 other mistakes that are exactly the same]

---
* 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?

#5 lore raw

Re: [PATCH v2] i18n.txt: camel case and monospace "i18n.commitEncoding"

Quoted 15 lines · Eric Sunshine
Quoted 7 lines · Junio C Hamano

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.

Quoted 6 lines
[jc: fixed 3 other mistakes that are exactly the same]

---
* So, while I still remember, I amended your commit and queued this.

Quoted 2 lines

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.

#6 lore raw

v3 cover doc: spell configuration variable names in camelCase

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(-)
Signature · 1 line
2.30.1-826-g07a034c5ea
#7 lore raw

PATCH v3 1/3 i18n.txt: camel case and monospace "i18n.commitEncoding"

From: Denton Liu <[email protected]>

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.

[jc: fixed 3 other mistakes that are exactly the same]
---
 Documentation/git-am.txt       | 2 +-
 Documentation/git-mailinfo.txt | 4 ++--
 Documentation/i18n.txt         | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)
Documentation/git-am.txt +1 -1
index 06bc063542..decd8ae122 100644
@@ -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
Documentation/git-mailinfo.txt +2 -2
index 7a6aed0e30..d343f040f5 100644
@@ -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.
Documentation/i18n.txt +1 -1
index 7e36e5b55b..6c6baeeeb7 100644
@@ -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]
Signature · 1 line
2.30.1-826-g07a034c5ea
#8 lore raw

PATCH v3 2/3 blame-options.txt: camelcase blame.blankBoundary

In reply to Junio C Hamano

All other references to blame.* configuration variables are camelCased already. Update this one to match.

---
 Documentation/blame-options.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/blame-options.txt +1 -1
index dc3bceb6d1..117f4cf806 100644
@@ -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
Signature · 1 line
2.30.1-826-g07a034c5ea
#9 lore raw

PATCH v3 3/3 index-format doc: camelCase core.excludesFile

In reply to Junio C Hamano
---
 Documentation/technical/index-format.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/technical/index-format.txt +2 -2
index 69edf46c03..8af608055f 100644
@@ -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
Signature · 1 line
2.30.1-826-g07a034c5ea
author
#10 lore raw

PATCH 2/3 git-cat-file.txt: monospace args and placeholders

In reply to Denton Liu

In modern documentation, args and placeholders are monospaced. Format all remaining args and placeholders as monospace.

---
 Documentation/git-cat-file.txt | 42 +++++++++++++++++-----------------
 1 file changed, 21 insertions(+), 21 deletions(-)
Documentation/git-cat-file.txt +21 -21
index 8e192d87db..987d170506 100644
@@ -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
Signature · 1 line
2.30.0.478.g8a0d178c01
#11 lore raw

Re: [PATCH 2/3] git-cat-file.txt: monospace args and placeholders

Documentation/git-cat-file.txt OPTIONS · line 119

Quoted 13 lines · Denton Liu

In modern documentation, args and placeholders are monospaced. Format all remaining args and placeholders as monospace.

---

Documentation/git-cat-file.txt +1 -1
@@ -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

author
#12 lore raw

PATCH 2/3 git-cat-file.txt: monospace args, placeholders and filenames

In reply to Denton Liu

In modern documentation, args, placeholders and filenames are monospaced. Apply monospace formatting to these objects.

---
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(-)
Documentation/git-cat-file.txt +28 -28
index 8e192d87db..a1c37a9e81 100644
@@ -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:
 
 ------------
Signature · 1 line
2.30.1.823.g0a3b79fd18
author
#13 lore raw

PATCH 3/3 git-cat-file.txt: remove references to "sha1"

In reply to Denton Liu

As part of the hash-transition, git can operate on more than just SHA-1 repositories. Replace "sha1"-specific documentation with hash-agnostic terminology.

---
 Documentation/git-cat-file.txt | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)
Documentation/git-cat-file.txt +5 -5
index 987d170506..ff89c7bfab 100644
@@ -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
Signature · 1 line
2.30.0.478.g8a0d178c01
#14 lore raw

Re: [PATCH 3/3] git-cat-file.txt: remove references to "sha1"

Documentation/git-cat-file.txt object, with placeholders of the form `%(atom)` expanded, followed by a · line 201

Quoted 11 lines · Denton Liu

As part of the hash-transition, git can operate on more than just SHA-1 repositories. Replace "sha1"-specific documentation with hash-agnostic terminology.

---

Documentation/git-cat-file.txt +1 -1
@@ -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"?

Documentation/git-cat-file.txt newline. The available atoms are: · line 218

Quoted 7 lines
Documentation/git-cat-file.txt +2 -2
@@ -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.

author
#15 lore raw

PATCH v2 1/1 git-cat-file.txt: remove references to "sha1"

In reply to Denton Liu

As part of the hash-transition, git can operate on more than just SHA-1 repositories. Replace "sha1"-specific documentation with hash-agnostic terminology.

---
 Documentation/git-cat-file.txt | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)
Documentation/git-cat-file.txt +6 -5
index a1c37a9e81..c404a9aae8 100644
@@ -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
Signature · 1 line
2.30.1.823.g0a3b79fd18
#16 lore raw

Re: [PATCH v2] git-cat-file.txt: remove references to "sha1"

Documentation/git-cat-file.txt object, with placeholders of the form `%(atom)` expanded, followed by a · line 203

Quoted 3 lines · Denton Liu

objectname::

Documentation/git-cat-file.txt +1 -1
-	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/.

Documentation/git-cat-file.txt newline. The available atoms are: · line 220

Quoted 9 lines
Documentation/git-cat-file.txt +3 -2
@@ -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.

Quoted 5 lines
Documentation/git-cat-file.txt +0 -1
@@ -235,14 +236,14 @@ newline.
 For example, `--batch` without a custom format would produce:
 
 ------------
-<sha1> SP <type> SP <size> LF

Documentation/git-cat-file.txt newline. · line 247

Quoted 10 lines
Documentation/git-cat-file.txt +2 -1
+<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.

author
#17 lore raw

v2 cover git-cat-file.txt: doc cleanup

In reply to Denton Liu

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

Signature · 1 line
2.30.1.823.g0a3b79fd18
author
#18 lore raw

PATCH v2 1/2 git-cat-file.txt: monospace args, placeholders and filenames

In modern documentation, args, placeholders and filenames are monospaced. Apply monospace formatting to these objects.

---
 Documentation/git-cat-file.txt | 56 +++++++++++++++++-----------------
 1 file changed, 28 insertions(+), 28 deletions(-)
Documentation/git-cat-file.txt +28 -28
index 8e192d87db..a1c37a9e81 100644
@@ -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:
 
 ------------
Signature · 1 line
2.30.1.823.g0a3b79fd18
author
#19 lore raw

PATCH v2 2/2 git-cat-file.txt: remove references to "sha1"

In reply to Denton Liu

As part of the hash-transition, git can operate on more than just SHA-1 repositories. Replace "sha1"-specific documentation with hash-agnostic terminology.

---
 Documentation/git-cat-file.txt | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)
Documentation/git-cat-file.txt +6 -5
index a1c37a9e81..4eb0421b3f 100644
@@ -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
Signature · 1 line
2.30.1.823.g0a3b79fd18
#20 lore raw

Re: [PATCH v2 0/2] git-cat-file.txt: doc cleanup

In reply to Denton Liu
Quoted 3 lines · Denton Liu

Denton Liu (2):
git-cat-file.txt: monospace args, placeholders and filenames git-cat-file.txt: remove references to "sha1"

Thanks, will queue.