diff mbox series

ls-tree doc: document interaction with submodules

Message ID patch-1.1-183b9639ae7-20220408T155704Z-avarab@gmail.com (mailing list archive)
State Accepted
Commit acd34fd5f60ab01e871dfa3a3bb8b81828ac181d
Headers show
Series ls-tree doc: document interaction with submodules | expand

Commit Message

Ævar Arnfjörð Bjarmason April 8, 2022, 4 p.m. UTC 
The ls-tree documentation had never been updated after it learned to
interact with submodules to explicitly mention them. The initial
support was added in f35a6d3bce7 (Teach core object handling functions
about gitlinks, 2007-04-09). E.g. the discussion of --long added in
f35a6d3bce7 (Teach core object handling functions about gitlinks,
2007-04-09) didn't explicitly mention them.

But this documentation added in 455923e0a15 (ls-tree: introduce
"--format" option, 2022-03-23) had no such excuse, and was actively
misleading by providing an exhaustive but incomplete list of object
types we'd emit.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---

On Thu, Apr 07 2022, Martin Ågren wrote:

> Commit 455923e0a1 ("ls-tree: introduce "--format" option", 2022-03-23)
> introduced `--format` and the various placeholders it can take, such as
> %(objectname) and %(objectsize).
>
> At some point when that patch was being developed, those placeholders
> had shorter names, e.g., %(name) and %(size), which can be seen in the
> commit message of 455923e0a1. One instance of "%(size:padded)" also
> managed to enter the documentation in the final version of the patch.
> Correct it to "%(objectsize:padded)"

Thanks, perhaps this is also worth taking before the release, it's a
rather trivial inaccuracy in the docs, but something that's new since
v2.36.0.

I have some local patches to make "git ls-tree --recurse-submodules"
work, and noticed this again after it conflicted with your now-landed
fix.

 Documentation/git-ls-tree.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

Comments

Junio C Hamano April 8, 2022, 6:20 p.m. UTC | #1 
Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

> Thanks, perhaps this is also worth taking before the release, it's a
> rather trivial inaccuracy in the docs, but something that's new since
> v2.36.0.
> ...
> diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
> index 8f31e2ee9d4..0240adb8eec 100644
> --- a/Documentation/git-ls-tree.txt
> +++ b/Documentation/git-ls-tree.txt
> @@ -151,11 +151,11 @@ names can be used:
>  objectmode::
>  	The mode of the object.
>  objecttype::
> -	The type of the object (`blob` or `tree`).
> +	The type of the object (`commit`, `blob` or `tree`).
>  objectname::
>  	The name of the object.
>  objectsize[:padded]::
> -	The size of the object ("-" if it's a tree).
> +	The size of a `blob` object ("-" if it's a `commit` or `tree`).
>  	It also supports a padded format of size with "%(objectsize:padded)".
>  path::
>  	The pathname of the object.

Makes sense.  Indeed we should have updated it when we added
gitlinks to trees.

Will queue.
diff mbox series

Patch

diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
index 8f31e2ee9d4..0240adb8eec 100644
--- a/Documentation/git-ls-tree.txt
+++ b/Documentation/git-ls-tree.txt
@@ -151,11 +151,11 @@  names can be used:
 objectmode::
 	The mode of the object.
 objecttype::
-	The type of the object (`blob` or `tree`).
+	The type of the object (`commit`, `blob` or `tree`).
 objectname::
 	The name of the object.
 objectsize[:padded]::
-	The size of the object ("-" if it's a tree).
+	The size of a `blob` object ("-" if it's a `commit` or `tree`).
 	It also supports a padded format of size with "%(objectsize:padded)".
 path::
 	The pathname of the object.