Re: [PATCH v2] doc: git-log: clarify --follow options

[Junio C Hamano <gitster@pobox.com>]

Tamir Duberstein <tamird@gmail.com> writes:

> I will reroll to say that `--follow` follows a single file beyond renames, works
> only with exactly one pathspec, and that directory pathspecs do not follow
> directory renames even though they still use the same traversal mode and can
> therefore show a different set of commits. I will also fix the subject and
> option ordering as suggested.

To be quite honest, the "--follow" option being what it is (i.e., a
checkbox option to claim we do support such an operation, without a
serious design and implementation), I'd rather see our documentation
being more honest and do not claim it works with pathspec at all.
When you use "--follow", you have to give a single filename, and
that file is followed across commits that renames it from some other
name, and then that file with the old name is followed.

If multiple histories are merged and if the file being followed
turns out to have come from different files on these different
histories, the "old name" the traversal is currently following is
not kept track of per traversal path, so we cannot expect the
feature to work with anything but a linear history, either.