git notes: notes

Just a quick note that the new notes feature can break things that parse
git log. For example a parser that assumes it can split the log on blank
lines to separate the header and commit message, can easily become
confused by the new blank line before "Notes:".

Might be worth documenting in release notes, maybe too late now though.
But really, it's all good, notes are a great feature.

PS, Has anyone thought about using notes to warn bisect away from
commits that are known to be unbuildable or otherwise cause bisection
trouble?

-- 
see shy jo

Joey Hess wrote:

Just a quick note that the new notes feature can break things that parse
git log.

Umm.  git-log is porcelain and we're allowed to change it.  Worse,
even the user can change it in very significant ways, just try:

  git config format.pretty email
  git log

For a better alternative, I'm afraid you'll either have to look to
git-rev-list (which also takes --pretty) or 'git cat-file --batch'.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

On Wednesday 20 January 2010, Joey Hess wrote:

Just a quick note that the new notes feature can break things that parse
git log. For example a parser that assumes it can split the log on blank
lines to separate the header and commit message, can easily become
confused by the new blank line before "Notes:".

As Thomas already stated, git log is porcelain, and its output format is not 
set in stone. If you need a stable, script-friendly format, you should 
probably use the --format option, or use plumbing instead (such as e.g. git 
rev-list, which also has a --format option).

Might be worth documenting in release notes, maybe too late now though.
But really, it's all good, notes are a great feature.

PS, Has anyone thought about using notes to warn bisect away from
commits that are known to be unbuildable or otherwise cause bisection
trouble?

No, I haven't thought of that specific use case. Great idea! :)

BTW, since I started talking about git notes, people on this list have found 
more and more interesting use cases for them:

- Free-form text extension to the commit message

- Help in bug tracking with header-like lines such as:
    - Causes-Bug: #12345
    - Fixes-Bug: #54321

- Store after-the-fact "Acked-By", "Reviewed-By", etc. annotations

- In a repo converted from a merge-unfriendly VCS (such as CVS), use notes
  to identify merges without having to rewrite Git history (note that you
  can also use grafts, or "git replace" to accomplish this).

- Refer to related commits elsewhere in the repo (i.e. relationships that
  are not already apparent from the commit graph)

- When cherry-picking, add a reverse link from the source commit to the
  cherry-picked commit (since it may be of interest to people reviewing the
  source commit

- Rebasing public branches is forbidden, but if you wanted to change that,
  you could potentially help solve it by using notes to add reverse links
  from source commits to rebased commits, so that downstream people could
  more easily traverse your history when rebasing/merging their own
  branches.

- Initially, there were some discussion whether it could also be used to
  guide git blame to make better decisions, although I don't currently see
  how that would be done in practice.

In any case, it seems the notes idea may have the potential to become one of 
the more useful features in Git.


Have fun! :)

...Johan


[1]: ...almost 3 years ago (wow, time flies...):
     http://article.gmane.org/gmane.comp.version-control.git/46883

-- 
Johan Herland, [off-list ref]
www.herland.net

Thomas Rast wrote:

Umm.  git-log is porcelain and we're allowed to change it.  Worse,
even the user can change it in very significant ways, just try:

  git config format.pretty email
  git log

Is git log --pretty=raw --raw really intended to be porcelain?
Above does not affect it.

For a better alternative, I'm afraid you'll either have to look to
git-rev-list (which also takes --pretty) or 'git cat-file --batch'.

I don't see a way to get the per-commit diff-tree info using rev-list.

-- 
see shy jo

Johan Herland wrote:

As Thomas already stated, git log is porcelain, and its output format is not 
set in stone. If you need a stable, script-friendly format, you should 
probably use the --format option, or use plumbing instead (such as e.g. git 
rev-list, which also has a --format option).

But git log --format=raw --raw output was changed by notes.

quoted

Might be worth documenting in release notes, maybe too late now though.
But really, it's all good, notes are a great feature.

PS, Has anyone thought about using notes to warn bisect away from
commits that are known to be unbuildable or otherwise cause bisection
trouble?

No, I haven't thought of that specific use case. Great idea! :)

Only problem I see with doing it is it might be too easy to overwrite
such a note with git notes edit -m

Did you consider having -m append a line to an existing note?

-- 
see shy jo

On Wednesday 20 January 2010, Joey Hess wrote:

Johan Herland wrote:

quoted

quoted

PS, Has anyone thought about using notes to warn bisect away from
commits that are known to be unbuildable or otherwise cause bisection
trouble?

No, I haven't thought of that specific use case. Great idea! :)

Only problem I see with doing it is it might be too easy to overwrite
such a note with git notes edit -m

Well, you would have to run "git notes edit -m" with core.notesRef or 
$GIT_NOTES_REF set to the notes ref where bisect information is stored (e.g. 
"refs/notes/bisect").

In any case, I would not use "git notes" to maintain the bisect hints. 
Rather, I'd add subcommands to "git bisect" that would take care of 
maintaining the notes tree @ "refs/notes/bisect". Much more user-friendly 
than telling the user to write their own bisect-notes by hand.

Did you consider having -m append a line to an existing note?

Hmm. Not really. The "git notes" porcelain was originally written by Dscho, 
and my builtin-ification of it (currently in 'pu') preserves the original 
semantics of "git notes edit -m". It might make sense to change the 
defaults; what do you think, Dscho?


Have fun! :)

...Johan

-- 
Johan Herland, [off-list ref]
www.herland.net

Hi,

On Thu, 21 Jan 2010, Johan Herland wrote:

On Wednesday 20 January 2010, Joey Hess wrote:

quoted

Did you consider having -m append a line to an existing note?

Hmm. Not really. The "git notes" porcelain was originally written by 
Dscho, and my builtin-ification of it (currently in 'pu') preserves the 
original semantics of "git notes edit -m". It might make sense to change 
the defaults; what do you think, Dscho?

I do not really care as long as there is a nice way to edit the complete 
note interactively.

Of course, I _do_ expect people to get confused just like they do with the 
current inconsistencies: "git commit -m" does not really append, but set 
the commit message, even if you amend a commit.

So maybe you want to use a different command line option for that.

Ciao,
Dscho

Johannes Schindelin wrote:

I do not really care as long as there is a nice way to edit the complete 
note interactively.

Of course, I _do_ expect people to get confused just like they do with the 
current inconsistencies: "git commit -m" does not really append, but set 
the commit message, even if you amend a commit.

So maybe you want to use a different command line option for that.

Maybe: git notes add [-m|-F]

-- 
see shy jo

On Wed, 2010-01-20 at 21:05 -0500, Johan Herland wrote:

On Wednesday 20 January 2010, Joey Hess wrote:

quoted

Johan Herland wrote:

quoted

quoted

PS, Has anyone thought about using notes to warn bisect away from
commits that are known to be unbuildable or otherwise cause bisection
trouble?

No, I haven't thought of that specific use case. Great idea! :)

[...]

In any case, I would not use "git notes" to maintain the bisect hints. 
Rather, I'd add subcommands to "git bisect" that would take care of 
maintaining the notes tree @ "refs/notes/bisect". Much more user-friendly 
than telling the user to write their own bisect-notes by hand.

I haven't read up on notes more than enough to know its in the pipe, but
I had a similar idea for using them to store bisect hints. I've been
doing a lot of bisecting lately into a range that had a couple dormant
bugs where I'm trying to bisect bug B but bug A prevents me from making
a determination. Rather than skip what I know is an interesting commit,
I cherry-pick the bugfix commit(s) A' and test that, then reset and
continue bisecting.

Teaching bisect to consistently skip a commit, or to automatically
squash in A' if we have A and not A', would be a desirable feature. I
will have to read up some more on notes.

On Thursday 21 January 2010, Joey Hess wrote:

Johannes Schindelin wrote:

quoted

I do not really care as long as there is a nice way to edit the
complete note interactively.

Of course, I _do_ expect people to get confused just like they do with
the current inconsistencies: "git commit -m" does not really append,
but set the commit message, even if you amend a commit.

So maybe you want to use a different command line option for that.

Maybe: git notes add [-m|-F]

Thanks for the suggestion. I've added this to the new iteration of the 
jh/notes series.


...Johan

-- 
Johan Herland, [off-list ref]
www.herland.net

On lundi 25 janvier 2010, John Koleszar wrote:

On Wed, 2010-01-20 at 21:05 -0500, Johan Herland wrote:

quoted

On Wednesday 20 January 2010, Joey Hess wrote:

quoted

In any case, I would not use "git notes" to maintain the bisect hints.
Rather, I'd add subcommands to "git bisect" that would take care of
maintaining the notes tree @ "refs/notes/bisect". Much more
user-friendly than telling the user to write their own bisect-notes by
hand.

I haven't read up on notes more than enough to know its in the pipe, but
I had a similar idea for using them to store bisect hints. I've been
doing a lot of bisecting lately into a range that had a couple dormant
bugs where I'm trying to bisect bug B but bug A prevents me from making
a determination. Rather than skip what I know is an interesting commit,
I cherry-pick the bugfix commit(s) A' and test that, then reset and
continue bisecting.

Teaching bisect to consistently skip a commit, or to automatically
squash in A' if we have A and not A', would be a desirable feature. I
will have to read up some more on notes.

Perhaps you can read about "git replace" in my article:

http://www.kernel.org/pub/software/scm/git/docs/git-bisect-lk2009.html

and/or my related presentation:

http://www.linux-kongress.org/2009/slides/fighting_regressions_with_git_bisect_christian_couder.pdf

I think in the long run it's much better to use git replace rather than 
notes, especially as replace refs for bisecting could be in their own 
refs/replace/bisect namespace. I may take the time to implement that soon 
if you or other people are interested.

Regards,
Christian.