Re: git-log on a file, and merges

[Piotr Krukowiecki <piotr.krukowiecki@gmail.com>]

On Fri, Aug 2, 2019 at 9:32 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Piotr Krukowiecki <piotr.krukowiecki@gmail.com> writes:
>
> > At this moment I'm not sure myself if I consider this a bug or not.
>
> This definitely is not a bug but is a designed and intended
> behaviour.

(generally speaking)
By "bug" I mean wrong behaviour. Designs can be buggy too.


> Think of running "git log" without "--full-history" that is limited
> with a pathspec as a tool to ask Git to show _one_ way (preferrably
> the simplest one) to explain how the current contents in paths that
> match the pathspec came to be.  The "just explain to me one way" is
> not about machine performance but reducing the clutter in the output
> to help human reader(s) reading an otherwise complex history.

From this point of view, the current behavior is good.

Although it's inconsistent. It works only for merges. If I'm on one
branch and change a file and then revert the change, "git log -- file"
will still show the commits. From your explanation, I'd expect those
commits to be skipped, since they are "no-op".


Also, I did read git-log docs before posting here, but still could not
find clear explanation for this behavior. Is it possible to improve
docs?

For example:

    [--] <path>…
    Show only commits that are enough to explain how the files that
match the specified paths came to be. See History Simplification below
for details and other simplification modes.

For me, the commits which modify the file are relevant to "how the
file come to be". They show what was tried and that finally the
original solution was choosen as the best. So not showing them is not
"enough to explain".
Also "History Simplification" is not very clear.

So maybe something like this? (just a rfc)


diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index b406bc4c48..bfb3d68b8b 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -91,9 +91,10 @@ include::line-range-format.txt[]
        section of linkgit:gitrevisions[7].

 [--] <path>...::
        Show only commits that are enough to explain how the files
-       that match the specified paths came to be.  See 'History
+       that match the specified paths came to be. Some commits may be
+       not shown even if they modify the specified paths. See 'History
        Simplification' below for details and other simplification
        modes.
 +
 Paths may need to be prefixed with `--` to separate them from
diff --git a/Documentation/rev-list-options.txt
b/Documentation/rev-list-options.txt
index bb1251c036..d2de33b219 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -317,13 +317,15 @@ endif::git-rev-list[]
 History Simplification
 ~~~~~~~~~~~~~~~~~~~~~~

 Sometimes you are only interested in parts of the history, for example the
-commits modifying a particular <path>. But there are two parts of
-'History Simplification', one part is selecting the commits and the other
-is how to do it, as there are various strategies to simplify the history.
+commits modifying a particular <path>. This is a two-step process:

-The following options select the commits to be shown:
+* initialial list of commits is selected
+
+* the list is simplified - some commits may be not shown
+
+The following options select the initial list of commits:

 <paths>::
        Commits modifying the given <paths> are selected.

@@ -337,9 +339,11 @@ The following options affect the way the
simplification is performed:
 Default mode::
        Simplifies the history to the simplest history explaining the
        final state of the tree. Simplest because it prunes some side
        branches if the end result is the same (i.e. merging branches
-       with the same content)
+       with the same content). This may happen for example when there
+       were commits which changed files, but then those changes were
+       reverted. Such commits will not be shown.

 --full-history::
        Same as the default mode, but does not prune some history.


-- 
Piotr Krukowiecki