Message ID | 20230328182650.GC18558@coredump.intra.peff.net (mailing list archive) |
---|---|
State | Accepted |
Commit | 15364d2a3cef397442033a3fec27d57007ca1c51 |
Headers | show |
Series | docs: document caveats of rev-list's object-name output | expand |
> > > Those names are really just intended as hints for pack-objects. I > > > suspect the documentation could be more clear about these limitations. > > > > That would indeed be great and would have likely prevented the obvious > > misconceptions on my side. > > Here's what I came up with. Thanks, this is one half of what I would have needed to read. > I also considered adding a specific "if you want the names of each file > in a range of commits, pipe to diff-tree" example. But it seemed like it > would clutter up this section. It might be OK as a stand-alone in the > EXAMPLES section, but should probably be done as a separate patch if > anyone is interested. That would be the other half. Since e.g. GitHub's own "best practice" examples do not use this pattern [0], I would assume that I'm not the only one who didn't know about it. [0] https://github.com/github/platform-samples/blob/master/pre-receive-hooks/block_file_extensions.sh
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 90c73d6708b..3000888a908 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -890,7 +890,7 @@ ifdef::git-rev-list[] Print the object IDs of any object referenced by the listed commits. `--objects foo ^bar` thus means ``send me all object IDs which I need to download if I have the commit - object _bar_ but not _foo_''. + object _bar_ but not _foo_''. See also `--object-names` below. --in-commit-order:: Print tree and blob ids in order of the commits. The tree @@ -920,7 +920,12 @@ ifdef::git-rev-list[] --object-names:: Only useful with `--objects`; print the names of the object IDs - that are found. This is the default behavior. + that are found. This is the default behavior. Note that the + "name" of each object is ambiguous, and mostly intended as a + hint for packing objects. In particular: no distinction is made between + the names of tags, trees, and blobs; path names may be modified + to remove newlines; and if an object would appear multiple times + with different names, only one name is shown. --no-object-names:: Only useful with `--objects`; does not print the names of the object