Re: [RFC PATCH 2/3] Documentation/git-rev-list: s/<commit>/<object>/

From: Matthew DeVore <matvore@google.com>
Date: Oct 20, 2018, 00:03 UTC
Message-ID: <CAMfpvh+CDc_jToDmZaAypqwXvrhJMO-_4sUWRcjXwwz6OHhAHA@mail.gmail.com>
In-Reply-To: <xmqq4ldo861m.fsf@gitster-ct.c.googlers.com>

On Sun, Oct 14, 2018 at 4:25 PM Junio C Hamano <gitster@pobox.com> wrote:

Show 27 quoted lines

>
> Matthew DeVore <matvore@google.com> writes:
>
> > -List commits that are reachable by following the `parent` links from the
> > -given commit(s), but exclude commits that are reachable from the one(s)
> > -given with a '{caret}' in front of them.  The output is given in reverse
> > -chronological order by default.
> > +List objects that are reachable by following references from the given
> > +object(s), but exclude objects that are reachable from the one(s) given
> > +with a '{caret}' in front of them.
> >
> > +By default, only commit objects are shown, and the commits are shown in
> > +reverse chronological order. The '--object' flag causes non-commit objects
> > +to also be shown.
> >
> > +You can think of this as a set operation.  Objects given on the command
> > +line form a set of objects that are reachable from any of them, and then
> > +objects reachable from any of the ones given with '{caret}' in front are
> > +subtracted from that set.  The remaining objects are what come out in the
> >  command's output.  Various other options and paths parameters can be used
> >  to further limit the result.
>
> I am not sure if this is a good rewrite.  It gives a false
> impression as if you'd not see anything if I did this:
>
>         git rev-list --objects ^master md/filter-trees:t/valgrind
>

Oh that's interesting. So my mental model conflicts with the command's behavior. It actually is surprising behavior because:

# this shows all files that were modified in the HEAD commit git rev-list --objects ^HEAD~1^{tree} HEAD:

# but this shows *all* files at HEAD git rev-list --objects ^HEAD~1 HEAD:

Which means that ^commit and ^non-commit are treated inherently differently. Maybe I should fix this bug before clarifying this documentation...

Show 5 quoted lines

> It is more like "this is a set operation across commits.  We also
> show objects that are reachable from the commits in the resulting
> set and are not reachable from the commits in the set that were
> excluded when --objects option is given".
>

That would be correct though it wouldn't tell that you can use "--objects ^foo-tree bar-tree." Without fixing the above bug, I could add to your wording something to the effect of "You can also use trees to include and exclude sets of objects rather than commits." Which implies that mixing "--objects ^commit tree" on the command line is undefined.