Junio C Hamano <junkio@xxxxxxx> writes:
> Your understanding needs to be clarified on how paths are
> filtered, and how log family and diff interacts, and probably
> these need to be better documented.
Having said that, I realized that I was making the same mistake
that our existing documentation was criticized for.
Let me first digress to address the documentation criticism.
The description on plumbing were (and still are) far more
thorough than porcelain-ish, and the conjecture by the person
who criticized them was because developers were keen documenting
the real work (plumbing) soon after they finished coding than
the frill (porcelain-ish).
I think the real reason for this is somewhat different. At
least to me, git.git was about the plumbing, and I did not want
to be in the Porcelain business at all [*1*]. Instead, I wanted
to encourage healthy competition among Porcelains. What was
shipped with git.git was meant to be "barely usable examples".
But this vision has not materialized fully yet, fortunately
because we did not end up splitting the userbase too early on.
But this was unfortunate for two reasons. One of them is that
different Porcelains would have brought completely different
ways of thinking and workflows into the picture.
Because git.git was primarily about the plumbing, the main focus
of the interface the plumbing offers was not about integration
and uniformity but modularity. Designing them as independent
building blocks as much as practical, and describing them fully,
were part of completing the plumbing. And the "barely usable
examples" started their lives as a set of trivial pipelines,
whose meaning was quite obvious and straightforward when you
understand the plumbing parts used in them. It also had UI
warts. "barely usable examples" cheated their command line
parsing, and the flags used by the plumbing showed through its
thin veneer to the UI used by the end users.
But that was a long time ago. Now we are in the v1.5.0 process,
whose theme is "usability and teachability".
Now, viewing in that light, what I described in the previous
message may have been a precise description of how things happen
to work currently, but it was not about the reason how and why
they were designed to be (because there was little design at the
UI level). We should instead (or at least "in addition") be
talking more about how things ought to be.
I described why --full-diff and --pickaxe-all are different
options, you can give 4 combinations of them, and how the
combinations work differently and why. That does not justify
that all of these four combinations make sense. In fact, I do
not think they do.
When pickaxe is used and --full-diff is given to 'log', I think
it does not make any sense not to use --pickaxe-all. So, I
think at the level of log family commands, unifying these two
flags make a lot of sense (although I earlier said "no").
Although --diff-filter does not have a corresponding option that
makes it behave all-or-none (i.e. an equivalent to --pickaxe-all),
it is conceivable that you might want to say:
$ git log --diff-filter=A --full-diff --diff-filter-all
to view commits that add new files with full diffs (not just
added paths). If we were to add that, I think it makes sense to
internally have a flag separate from pickaxe-all to express it
but when 'log' uses --full-diff, it does not make any sense not
to enable it. In other words,
$ git log -M --diff-filter=R -Sstring --full-diff
should internally enable pickaxe-all and diff-filter-all and
show all of diff that has renames in the paths that change
"string" [*2*].
[Footnote]
*1* I once wanted to do a Porcelain of my own, after finding it
distasteful that Cogito tried to hide the index back when it did
not even use the index properly for merges. But things have
been improved quite a lot in Cogito land and I do not have
anything against it anymore. And as you all know, I like StGIT
very much.
*2* This is actually in line with what we did in 582af688. As a
member of 'log' family, 'git log' were originally meant to show
commit messages for all commits that revision traversal gave it,
regardless of the diff output (and without the diffcore
transformation, when revision traversal said a commit is
interesting, the commit always has some diff or a merge). When
used in conjunction with --pickaxe and --diff-filter, however,
this layering made the command much less useful. We fixed the
problem by violating the layering and made the log command aware
of the underlying diff machinery's output filter. I think the
same would apply to the issue we are currently discussing.
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html