Merge branch 'jk/document-rev-list-object-name'

Document what the pathname-looking strings in "rev-list --object"
output are for and what they mean.

* jk/document-rev-list-object-name:
  docs: document caveats of rev-list's object-name output

diff --combined Documentation/rev-list-options.txt
index 90c73d6708b1d7dc90f50380c20521a1f713ff90,43f293e701467b523e8891161e15f0be62a41123..3000888a90852f6bd95eee5b40dc2f184ddd3dc9
--- 1/Documentation/rev-list-options.txt
--- 2/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@@ -195,14 -195,6 +195,14 @@@ respectively, and they must begin with 
  or `--all`. If a trailing '/{asterisk}' is intended, it must be given
  explicitly.
  
 +--exclude-hidden=[fetch|receive|uploadpack]::
 +      Do not include refs that would be hidden by `git-fetch`,
 +      `git-receive-pack` or `git-upload-pack` by consulting the appropriate
 +      `fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs`
 +      configuration along with `transfer.hideRefs` (see
 +      linkgit:git-config[1]). This option affects the next pseudo-ref option
 +      `--all` or `--glob` and is cleared after processing them.
 +
  --reflog::
        Pretend as if all objects mentioned by reflogs are listed on the
        command line as `<commit>`.
@@@ -890,7 -882,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 -912,12 +920,12 @@@
  
  --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
@@@ -1101,12 -1098,12 +1106,12 @@@ preferred format.  See the `strftime` m
  format placeholders. When using `-local`, the correct syntax is
  `--date=format-local:...`.
  
 -`--date=default` is the default format, and is similar to
 -`--date=rfc2822`, with a few exceptions:
 +`--date=default` is the default format, and is based on ctime(3)
 +output.  It shows a single line with three-letter day of the week,
 +three-letter month, day-of-month, hour-minute-seconds in "HH:MM:SS"
 +format, followed by 4-digit year, plus timezone information, unless
 +the local time zone is used, e.g. `Thu Jan 1 00:00:00 1970 +0000`.
  --
 -      - there is no comma after the day-of-week
 -
 -      - the time zone is omitted when the local time zone is used
  
  ifdef::git-rev-list[]
  --header::