Re: [PATCH 1/1] Add feature to show log as a tree

I am not sure what you mean by a "tree". It definitely is not a
tree perceived by Git users (which is what represents a directory
structure), and abusing the established term is confusing.

I called it tree because the output looks like (right half) of a tree.
I'm open to alternatives though.

There is no inherent ordering among children of a given commit, so
you'd invent some way to define what "the first child" is. That
much can be read from the above, but what is missing is why do you
even need to bother. What benefit do users get by identifying "the
first" child and cutting all others off---that is the necessary
justification for this change, which is missing from the above
explanation.

Right, in my mind the problem statement is so clear and I didn't write
it down. There should have been an introduction paragraph.

Problem I want to solve. The --graph output is useful but often
unreadable, due to the many parallel lines. On the other hand, with the
default straight line log output all structure is lost. I am trying some
middle ground to see merge structure, but keep history readable. I
noticed in particular the branch point causes a line to go around or go
in between many commits leading to clutter, so I want to remove these.
By itself the exact point branched from is rarely important (at least to
me). And if it is, then there still is --graph :-).

"A (depth) level" is poorly explained---in fact, it is not explained
what it means at all. "We designate the first child of each commit
by some magic" is all we can read from it.

When processing the commit nodes. Start with depth level 0. Given some
current depth level D, assign depth level D, D+1, ... D+N-1 to the N
parents of a (merge) commit. Recurse.

In the output, the depth level is more or less the column number the
star '*' is in. (Although after merges of merges, there will be gaps in
the level numbering.)

After explaining "some magic" in a more meaningful way, perhaps
you'd realize that you'd want to stop saying "first child". It

OK well, the term "first parent" is already in the man page, right?
--first-parent. So the first child of a commit is the commit C among all
children H, such that when all of H are traced back to a common point S,
the trace line from C is the one that ends being the first parent of S.

ignore all side branches and concentrate only on the trunk of a
tree). And I'd probably call each child that is on the "trunk" line
of the most important lineage "primary child" or something like
that.

Sort of, but remember this works recursive, there can be merges of
merges. Therefore the output is not a single trunk line. In other words,
the above commit S doesn't need to be on the trunk (or, '*' completely
left in the graph output).

In any case, if this is to sit next to and be friends with
"--topo-order", the option should be named as "--some-order".
The option name "--tree" (or "--blob", "--tag", or "--commit" for
that matter) is obviously unacceptable if the option is about
specifying how the commits in the "git log" output are ordered.

I see it as alternative to the --graph option. I also made it jump
there, but maybe gotos are rejected from style point of view. In this
case I thought it would be clear to see it as alternative to --graph.

It doesn't do justice in my opinion to call it --graph --micha-order (or
whatever ;-)), as it is not only about changing the order of commit
display. But again, I'm open to alternatives, I can make a personal
alias anyway :-).

Having said that, if you are omitting commits that are not on the
primary lineage of the history, then this is not "--anything-order"
option, in which case it may want to sit next to and be friends with

Ah no, it doesn't omit any commits. All commits are displayed.

Without clear explanation of what the change attempts to achieve in
docs and tests, there is no way to review to see if the new code is
correct.

How can I add tests for this feature? I'm also open to what kinds of
documentation to add, as I find it way easier to explain when you
actually run it to see the output it generates, than from abstract
paragraph of documentation text (like a manpage has). Some
mathematical-type of explanation like above is also not really
immediately enlightening, and also not necessary to use it I think.