patch, 2 partsA couple of tweaks in git-for-each-ref.txt

I was reading the man page on git-for-each-ref and noticed a few bugs and missing Authors and Documentation sections.

Sorry if I wasn't supposed to add them. I don't know if such editing should be done exclusively by the authors themselves or is it OK for others to do so. Just thought someone overlooked missing sections in the docs for this command.

Alexei Sholik (2):
  Documentation: remove redundant colons in git-for-each-ref.txt
  Add Author and Documentation sections to git-for-each-ref.txt

 Documentation/git-for-each-ref.txt |   18 +++++++++++++++---
 1 files changed, 15 insertions(+), 3 deletions(-)

-- 1.7.2.3

Signed-off-by: Alexei Sholik <alcosholik@gmail.com>
---
 Documentation/git-for-each-ref.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

Alexei Sholik venit, vidit, dixit 08.03.2011 14:16:

Maybe those were meant to be items in a labelled list, but asciidoc doesn't seem to recognize the "::" as such here, so I think this change is fine.

Michael

Signed-off-by: Alexei Sholik <alcosholik@gmail.com>
---
 Documentation/git-for-each-ref.txt |   12 ++++++++++++
 1 files changed, 12 insertions(+), 0 deletions(-)

Alexei Sholik venit, vidit, dixit 08.03.2011 14:16:

+Evangelisation --------------- Jeff King <peff@peff.net>

Just kidding!

(Jeff is the 2nd main f-e-r author, but Junio created it.)

Michael ;)

On 9 March 2011 10:08, Michael J Gruber <git@drmicha.warpmail.net> wrote:

I meant no offense. Just ran this command

git blame -p "$1" | awk '$1 ~ /author$/ { print substr($0, length("author "), length($0)) }' | sort | uniq -c | sort -nr

on the for-each-ref.c and saw that Junio had the first place by a relatively large margin.

Similarly, the git-for-each-ref.txt (I used plain git blame on this one) has mostly been composed by Junio. Surely, it's not my privilege to decide on the list of authors, but I wonder why the original authors haven't claimed their rightful place in the docs.

On Wed, 2011-03-09 at 14:14 +0200, Alexei Sholik wrote:

Wrap that up in a script and submit /that/ as a patch ;)

On Thu, Mar 17, 2011 at 02:20:08PM +0000, Will Palmer wrote:

That just counts the number of commits that have any surviving line in a given file. So it's slightly better than "shortlog -ns" in that it removes commits whose contents have been totally rewritten (and it properly handles content-following). But if you are going to use blame, the more interesting measure is probably a count of lines attributed to each author. Something like:

  git blame -p "$1" | perl -ne '
    if (/^([0-9a-f]{40})/) {
      $sha1 = $1;
      $count{$sha1}++;
    }
    elsif (/^author (.*)/) {
      $author{$sha1} = $1;
    }
    END {
      foreach my $sha1 (keys(%count)) {
        $r{$author{$sha1}} += $count{$sha1};
      }
      foreach my $a (sort { $r{$b} <=> $r{$a} } keys(%r)) {
        print "$r{$a} $a\n";
      }
    }
  '

-Peff

Ah, gmail has cut out the CC list. Below is my reply to a previous message by Will Palmer.

I think, it would be nice to have a tool, which output all the different stats about the repo, maybe even in a gui. But it definitely doesn't belong in the Git project.

-- Best regards, Alexei Sholik

---------- Forwarded message ----------
From: Alexei Sholik <alcosholik@gmail.com>
Date: 17 March 2011 16:45
Subject: Re: [PATCH 2/2] Add Author and Documentation sections to
git-for-each-ref.txt
To: Will Palmer <wmpalmer@gmail.com>

On 17 March 2011 16:20, Will Palmer <wmpalmer@gmail.com> wrote:

This script alone is not very useful. I was thinking about writing a collection of scripts to gather different stats from the repository history. However, it would be a different project altogether, not a part of Git. The Future Git should be portable and shiny ;)

On Thu, Mar 17, 2011 at 09:51:55PM +0200, Alexei Sholik wrote:

Check out:

  http://gitstats.sourceforge.net/

It currently doesn't have a lot of per-file stats like this, but I'm sure patches are welcome. :)

-Peff

On 17 March 2011 21:54, Jeff King <peff@peff.net> wrote:

Hey thanks! I've just found out that my current project has more png files than source code files :)

The tool itself looks rough in terms of the output it produces, but I'm definitely going to look at the code more closely. Thanks for the hint.

Michael J Gruber <git@drmicha.warpmail.net> writes:

Thanks for bringing this up.

In the very early days (like back when the project was only 12 months old) it made sense to record that this and that command were primarily done by that person. But I don't think it is a good idea anymore.

For example, format-patch was my invention and all the code was mine back when it was a script. Later it was reimplemented in C by Dscho based on my earlier work. But a large part of the actual implementation was done by using the generic revision traversal machinery, whose primary authors back then were Linus and me. The silly original UI design everybody hates ("format-patch <upstream>" is not similar to 'git log <upstream>..'") is "owned" by me, the user facing main() implementation is "owned" by Dscho, and the backend machinery is "owned" by Linus and me.

Who should we list, and more importantly, does it make sense to keep the list up to date as the system evolves?

As the project and the community grew, and also as the internal machinery infrastructure got more modularized, I think ownership at the individual command level has become almost meaningless concept.

Same reasoning applies to the "Documented by". I think it's time for these two sections to go from most (if not all) pages.

On Wed, Mar 09, 2011 at 12:17:53PM -0800, Junio C Hamano wrote:

Yeah, I would just as soon drop Author and Documented-by fields in all manpages. We could replace them with a single "Credits" in git(1). It can either mention nobody, very few people (like Linus as the originator and Junio as the long-time maintainer), or the top N (for N < 20 or so) people in shortlog. And then mention that you can run shortlog yourself.

I would probably do something like this:

Jeff King <peff@peff.net> writes:

Sounds sensible.

On Thu, Mar 10, 2011 at 03:09:43PM -0800, Junio C Hamano wrote:

If you want to see what the full patch would look like, you can fetch it from:

  git://github.com/peff/git.git jk/doc-credits

The patch itself is rather large, so I didn't want to post it. I don't know if we should extract the list of people who are being dropped and check if they have any objection. You can get a partial list with:

   git show jk/doc-credits^ |
     grep ^- |
     perl -lne 'print for /<(.*?)>/g' |
     sort -u

though some people are mentioned only by name, not by email.

-Peff

Jeff King <peff@peff.net> writes:

Thanks; will immediately queue to 'pu' for wider dissemination. I think the changes are all sensible. The credits are there in the shortlog, and the contributors' names are displayed at one of the more prominent git related sites, namely http://git-scm.com/about/, to honor them, so I don't think keeping already stale information on each and every manpage is warranted.

On 11 March 2011 00:37, Jeff King <peff@peff.net> wrote:

The last sentence could be a little bit more informative for casual
git-users, something like
  For a complete list of contributors, see http://git-scm.com/about,
or (if you are a true geek) linkgit:git-shortlog[1] and
linkgit:git-blame[1].

Other than that, I totally agree with the idea.

On Sat, Mar 12, 2011 at 11:52:23AM +0200, Alexei Sholik wrote:

Yeah, I was tempted to put in explicit instructions but opted to keep it simple. I forgot about the credits listing at git-scm.com, though. Maybe this on top of my other patches?

-- >8 --
Subject: [PATCH] docs: point git.txt author credits to git-scm.com

There is a nice shortlog-ish output of the authors there. We also point people directly to shortlog, but of course they might be reading the documentation online or from a binary package of git.

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/git.txt |    6 ++++--
 1 files changed, 4 insertions(+), 2 deletions(-)

Jeff King <peff@peff.net> writes:

Looks sensible.

I see you rebased your jk/doc-credits topic at GitHub but haven't queued this one yet, so I won't be pulling, but give me a holler when the branch is ready to be pulled into 'master'. I'll then push the result out after running final "make doc" check on a few platforms I have and eyeballing the output.

Thanks.

On Sat, Mar 12, 2011 at 10:34:08PM -0800, Junio C Hamano wrote:

It's pushed now. I rebase my topics aggressively on top of master (which you saw), but I don't always push out regularly. Since my main output is patches to the list, in general I assume nobody is actually looking at my topics directly. :) Let me know if some other strategy would be better[1].

I've done a perfunctory check over the changes, but there are a lot of them, so another set of eyeballs on the output is appreciated.

-Peff

[1] I have mixed feelings about the aggressive rebasing. Our 'master' is pretty stable, so I don't feel the need to build off the last tagged release. But rebasing a lot does make it hard for others to follow the topic, and it makes it hard to organize my work with you queue in pu, and then merge to 'next' and 'master'. However, I haven't found a satisfactory solution to tracking patches as they move through the workflow of local development, sent to list, and applied upstream.

Git-cherry sort of does this, but patch-ids miss a lot of cases: patches tweaked in transit, patches applied on a different commit, or even patches taken partially or split up. So I rebase frequently, and as patches get picked up in master, the branches dwindle to empty. Suggestions welcome if anybody else has figured out something clever.

-Peff

Jeff King <peff@peff.net> writes:

In a very busy project (like the kernel), it would make sense to build off of the last tagged release when your interaction with the upstream is primarily based on patch exchange. But I think that is primarily because the maintainer and the reviewer do not have to ask "where does this apply to? It does not apply to my tree; please resend" if you did so. Because our "master" does not move so fast, sending a complete patch series based on any commit that was once at the tip of "master" works similarly well, especially because "am -3" works well in such an environment if "master" is never rewound.

But if your interaction with the upstream is merge based, I think it is preferrable to base your fork point as if you are the person at the upstream. There is no "where does this apply to" at that point, and you have a larger responsibility and say in the final shape of the history.

Namely (I know you know this, and I am writing this primarily for other people on the list):

 - an fix would be appropriate to be made on top of the oldest maintenance
   track that contains the commit that introduced a bug (or even directly
   on the buggy commit itself), as long as merging up from maint-O to
   maint-N (O < N) to master is simple enough;

 - For enhancement patches that do not deserve to be backported to
   maintenance branches, "master" is a good place to start.

For this topic, you could have said that this is a documentation bug fix and started the topic at the tip of maint, given that this is a fairly low-risk change, and that we haven't added any new file between maint and master that requires an evil merge to fix up. Or you can say that this is very minor and not worth fixing in maintenance track to fork from master.

A solution to string different iterations of the same patch together, perhaps using notes as the storage media, that makes it easier to view the changes between different iterations? I think Shawn does something like that in Gerrit code review.

When I rebase, I tend to keep the base stable (in other words, I don't use "rebase" in order to change the base, but to rewrite individual patches), too keep comparison between iterations simpler, but I haven't found a satisfactory solution for such a comparison for changes near the tip of longer series.

Junio C Hamano venit, vidit, dixit 13.03.2011 08:33:

In a way it's comforting to know that even long-time contributors like Jeff haven't found a good workflow for git.git patch lifetime management yet. But there's progress, such as "commit --notes". I'm also fiddling with refname notes (so you could store the cover-letter as a note to the branch name) and have working code I'll send soon.

As far as keeping track of patch versions (without topgit) goes I've been thinking about "mergy rebase". Before it sits around any longer, I'll include a rough concept below.

And sorry for thread hijacking - it wasn't me :)

Michael

Say, you start developping a patch series on a branch "topic":

*--A1--B1--C1=topic

Then you rewrite/fixup your series:

*--A2--B2--C2=topic

The previous versions are lost (in the reflog).

With a mergy rebase, a rewrite/fixup would produce:

*--A1--B1--C1
 \  \   \   \
  ---A2--B2--C2=topic

That is, "log --first-parent topic" would always walk the current version of the topic branch, but the previous one is still accessible:

*--A1--B1--C1
 \  \   \   \
  ---A2--B2--C2
   \  \   \   \
    ---A3--B3--C3
     \  \   \   \
      ---A4--B4--C4=topic

"log --second-parent C4" will give you the history of the patch C through the different versions of ypur patch series.

(And yes, I have a WIP for --second-parent.)

Downside is that all those merges are evil, of course. But do not be afraid...

On Sat, Mar 12, 2011 at 11:33:52PM -0800, Junio C Hamano wrote:

I don't necessarily care about different iterations of the patch on my end. Usually when I discard an old version I don't go back to it, and in the rare case that I do, it is simple enough to pull it from the reflog or from the mailing list.

What I mean is lining up what I have locally (and what I send) with what ends up in your repository. Which can have arbitrary changes from the original. I don't think there is a general solution. In theory you could take a single patch of mine, split it into two, then mark up each half. I know you have the sense not to do this, but there are simpler cases that still cause problems.

For example, in my recent trace-sifter series, you took some squashes from other people on the early bits, and those impacted the text of later bits. So there was no way for patch-id to link up the patches.

Rebasing at least faces me with the conflicts over the rewrite, and I can manually check each conflict and say "OK, it looks like he took my patch, but this part had to be rewritten". And then I can either accept your rewrite (by resolving in favor of you), or I can rework my patch to do what I think should be done on top of yours, and then submit my new one on top.

I could also use Jay's suggested "loose patch id", and link things up by commit author and message. Unless you do something drastic like splitting a patch in two (or merging two patches into one), then I can create the correlation. But it makes me a little nervous, because the content of your version may not be the same as mine. And probably I should be reviewing it before throwing away my version in favor of yours.

-Peff

Alexei Sholik <alcosholik@gmail.com> writes:

I actually wanted to propose dropping the "authors" and "documentation by" sections from all the pages a few years ago, but didn't push it very far. Your patch moves things the other direction, but the result becomes more consistent, so it is a good change nevertheless.

Thanks.