[PATCH 0/2] A couple of tweaks in git-for-each-ref.txt

[PATCH 0/2] A couple of tweaks in git-for-each-ref.txt

[Alexei Sholik]

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

[PATCH 1/2] Documentation: remove redundant colons in git-for-each-ref.txt

[Alexei Sholik]

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

diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index fac1cf5..bffb5d2 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -123,7 +123,7 @@ EXAMPLES
 --------
 
 An example directly producing formatted text.  Show the most recent
-3 tagged commits::
+3 tagged commits:
 
 ------------
 #!/bin/sh
@@ -140,7 +140,7 @@ Ref: %(*refname)
 
 
 A simple example showing the use of shell eval on the output,
-demonstrating the use of --shell.  List the prefixes of all heads::
+demonstrating the use of --shell.  List the prefixes of all heads:
 ------------
 #!/bin/sh
 
@@ -154,7 +154,7 @@ done
 
 
 A bit more elaborate report on tags, demonstrating that the format
-may be an entire script::
+may be an entire script:
 ------------
 #!/bin/sh
 
-- 
1.7.2.3

Re: [PATCH 1/2] Documentation: remove redundant colons in git-for-each-ref.txt

[Michael J Gruber]

Alexei Sholik venit, vidit, dixit 08.03.2011 14:16:
> Signed-off-by: Alexei Sholik <alcosholik@gmail.com>
> ---
>  Documentation/git-for-each-ref.txt |    6 +++---
>  1 files changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
> index fac1cf5..bffb5d2 100644
> --- a/Documentation/git-for-each-ref.txt
> +++ b/Documentation/git-for-each-ref.txt
> @@ -123,7 +123,7 @@ EXAMPLES
>  --------
>  
>  An example directly producing formatted text.  Show the most recent
> -3 tagged commits::
> +3 tagged commits:
>  
>  ------------
>  #!/bin/sh
> @@ -140,7 +140,7 @@ Ref: %(*refname)
>  
>  
>  A simple example showing the use of shell eval on the output,
> -demonstrating the use of --shell.  List the prefixes of all heads::
> +demonstrating the use of --shell.  List the prefixes of all heads:
>  ------------
>  #!/bin/sh
>  
> @@ -154,7 +154,7 @@ done
>  
>  
>  A bit more elaborate report on tags, demonstrating that the format
> -may be an entire script::
> +may be an entire script:
>  ------------
>  #!/bin/sh
>  

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

[PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Alexei Sholik]

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

diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index bffb5d2..ceef54b 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -204,3 +204,15 @@ eval=`git for-each-ref --shell --format="$fmt" \
 	refs/tags`
 eval "$eval"
 ------------
+
+Author
+------
+Written by Junio C Hamano <gitster@pobox.com>.
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the linkgit:git[1] suite
-- 
1.7.2.3

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Michael J Gruber]

Alexei Sholik venit, vidit, dixit 08.03.2011 14:16:
> Signed-off-by: Alexei Sholik <alcosholik@gmail.com>
> ---
>  Documentation/git-for-each-ref.txt |   12 ++++++++++++
>  1 files changed, 12 insertions(+), 0 deletions(-)
> 
> diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
> index bffb5d2..ceef54b 100644
> --- a/Documentation/git-for-each-ref.txt
> +++ b/Documentation/git-for-each-ref.txt
> @@ -204,3 +204,15 @@ eval=`git for-each-ref --shell --format="$fmt" \
>  	refs/tags`
>  eval "$eval"
>  ------------
> +
> +Author
> +------
> +Written by Junio C Hamano <gitster@pobox.com>.
> +
> +Documentation
> +--------------
> +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
> +
> +GIT
> +---
> +Part of the linkgit:git[1] suite

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

Just kidding!

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

Michael ;)

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Alexei Sholik]

On 9 March 2011 10:08, Michael J Gruber <git@drmicha.warpmail.net> wrote:
> +Evangelisation
> ---------------
> Jeff King <peff@peff.net>
>
> Just kidding!
>
> (Jeff is the 2nd main f-e-r author, but Junio created it.)
>
> Michael ;)
>

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.

-- 
Best regards,
Alexei Sholik

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Will Palmer]

On Wed, 2011-03-09 at 14:14 +0200, Alexei Sholik wrote:
> .................. 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.
> 

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

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Jeff King]

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

> On Wed, 2011-03-09 at 14:14 +0200, Alexei Sholik wrote:
> > .................. 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.
> > 
> 
> Wrap that up in a script and submit /that/ as a patch ;)

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

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Alexei Sholik]

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:
> On Wed, 2011-03-09 at 14:14 +0200, Alexei Sholik wrote:
>> .................. 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.
>>
>
> Wrap that up in a script and submit /that/ as a patch ;)
>
>

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 ;)

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Jeff King]

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

> 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.

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

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Alexei Sholik]

On 17 March 2011 21:54, Jeff King <peff@peff.net> wrote:
> On Thu, Mar 17, 2011 at 09:51:55PM +0200, Alexei Sholik wrote:
>
>> 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.
>
> 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
>

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.

-- 
Best regards,
Alexei Sholik

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Junio C Hamano]

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

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

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.

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Jeff King]

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

> 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.

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:

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 0c32d45..4323843 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -745,16 +745,10 @@ unmerged version of a file when a merge is in progress.
 
 Authors
 -------
-* git's founding father is Linus Torvalds <torvalds@osdl.org>.
-* The current git nurse is Junio C Hamano <gitster@pobox.com>.
-* The git potty was written by Andreas Ericsson <ae@op5.se>.
-* General upbringing is handled by the git-list <git@vger.kernel.org>.
-
-Documentation
---------------
-The documentation for git suite was started by David Greaves
-<david@dgreaves.com>, and later enhanced greatly by the
-contributors on the git-list <git@vger.kernel.org>.
+Git was started by Linus Torvalds, and is currently maintained by Junio
+C Hamano. Numerous contributions have come from the git mailing list
+<git@vger.kernel.org>. For a complete list of contributors, see
+linkgit:git-shortlog[1] and linkgit:git-blame[1].
 
 Reporting Bugs
 --------------

And then a follow-on patch to drop the Authors section from all of the
other pages.

-Peff

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Wed, Mar 09, 2011 at 12:17:53PM -0800, Junio C Hamano wrote:
>
>> 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.
>
> 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.

Sounds sensible.

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Jeff King]

On Thu, Mar 10, 2011 at 03:09:43PM -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.
> 
> Sounds sensible.

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

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Thu, Mar 10, 2011 at 03:09:43PM -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.
>> 
>> Sounds sensible.
>
> 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.

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.

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Alexei Sholik]

On 11 March 2011 00:37, Jeff King <peff@peff.net> wrote:
> -The documentation for git suite was started by David Greaves
> -<david@dgreaves.com>, and later enhanced greatly by the
> -contributors on the git-list <git@vger.kernel.org>.
> +Git was started by Linus Torvalds, and is currently maintained by Junio
> +C Hamano. Numerous contributions have come from the git mailing list
> +<git@vger.kernel.org>. For a complete list of contributors, see
> +linkgit:git-shortlog[1] and linkgit:git-blame[1].

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.

-- 
Best regards,
Alexei Sholik

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Jeff King]

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

> On 11 March 2011 00:37, Jeff King <peff@peff.net> wrote:
> > -The documentation for git suite was started by David Greaves
> > -<david@dgreaves.com>, and later enhanced greatly by the
> > -contributors on the git-list <git@vger.kernel.org>.
> > +Git was started by Linus Torvalds, and is currently maintained by Junio
> > +C Hamano. Numerous contributions have come from the git mailing list
> > +<git@vger.kernel.org>. For a complete list of contributors, see
> > +linkgit:git-shortlog[1] and linkgit:git-blame[1].
> 
> 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].

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(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 4323843..5e57f69 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -747,8 +747,10 @@ Authors
 -------
 Git was started by Linus Torvalds, and is currently maintained by Junio
 C Hamano. Numerous contributions have come from the git mailing list
-<git@vger.kernel.org>. For a complete list of contributors, see
-linkgit:git-shortlog[1] and linkgit:git-blame[1].
+<git@vger.kernel.org>. For a more complete list of contributors, see
+http://git-scm.com/about. If you have a clone of git.git itself, the
+output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you
+the authors for specific parts of the project.
 
 Reporting Bugs
 --------------
-- 
1.7.2.5.18.g3ffb9

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> 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?

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.

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Jeff King]

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

> 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.

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

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> [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.

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.

> 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.

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.

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 13.03.2011 08:33:
> Jeff King <peff@peff.net> writes:
> 
>> [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.
> 
> 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.
> 
>> 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.
> 
> 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.
> 

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...

Re: [PATCH 2/2] Add Author and Documentation sections to git-for-each-ref.txt

[Jeff King]

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

> > 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.
> 
> 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.

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

Re: [PATCH 0/2] A couple of tweaks in git-for-each-ref.txt

[Junio C Hamano]

Alexei Sholik <alcosholik@gmail.com> writes:

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

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.