{"thread":{"id":"24688","subject":"git notes primer?","startedAt":"2010-08-10T08:40:06Z","lastAt":"2010-08-11T09:52:03Z","messageCount":4,"participants":["Thomas Koch","Michael J Gruber","Jonathan Nieder","Johan Herland"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"147613","messageId":"201008101040.07172.thomas@koch.ro","threadId":"24688","inReplyTo":null,"subject":"git notes primer?","fromName":"Thomas Koch","fromEmail":"thomas@koch.ro","sentAt":"2010-08-10T08:40:06Z","receivedAt":"2010-08-10T08:40:06Z","isPatch":false,"sender":{"key":"thomas@koch.ro","avatar":null},"body":"Hi,\n\nI'm working on a patch management system as topgit, but without the \ncomplexity:\nhttp://koch.ro/blog/index.php?/archives/139-tnt-is-not-topgit.html\n\nBefore I continue with my current design, I wanted to have a look at git \nnotes, whether it would provide better mechanisms then tracking my meta \ninformations in a hidden background branch. (Much like pristine-tar does.)\n\nHowever I couldn't get a grip on git notes:\n\n- Is git notes the only command that works on notes?\n- How are notes saved inside GIT?\n- Is git notes and it's implementation stable now?\n- Are there any tutorials on workflows with git notes?\n- What different use cases of git notes do you know?\n- What use cases triggered the development of git notes in the first place?\n\nThank you for your time,\n\nThomas Koch, http://www.koch.ro\n"},{"id":"147625","messageId":"4C6138D7.6050300@drmicha.warpmail.net","threadId":"24688","inReplyTo":"201008101040.07172.thomas@koch.ro","subject":"Re: git notes primer?","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-08-10T11:32:39Z","receivedAt":"2010-08-10T11:32:39Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Thomas Koch venit, vidit, dixit 10.08.2010 10:40:\n> Hi,\n> \n> I'm working on a patch management system as topgit, but without the \n> complexity:\n> http://koch.ro/blog/index.php?/archives/139-tnt-is-not-topgit.html\n> \n> Before I continue with my current design, I wanted to have a look at git \n> notes, whether it would provide better mechanisms then tracking my meta \n> informations in a hidden background branch. (Much like pristine-tar does.)\n> \n> However I couldn't get a grip on git notes:\n> \n> - Is git notes the only command that works on notes?\n> - How are notes saved inside GIT?\n\nFor thoese two it's best to look at the textconv-cache facility\ndeveloped by Jeff King which uses notes internally, without creating\n\"proper\" notes.\n\n> - Is git notes and it's implementation stable now?\n\nThe API should be as stable as any API on master.\n\n> - Are there any tutorials on workflows with git notes?\n> - What different use cases of git notes do you know?\n> - What use cases triggered the development of git notes in the first place?\n\nThe origin was being able to amend/annotate commit messages without\nrewriting history.\n\nOthers may have to say more ;)\n\nMichael\n"},{"id":"147716","messageId":"20100811051036.GA639@burratino","threadId":"24688","inReplyTo":"201008101040.07172.thomas@koch.ro","subject":"Re: git notes primer?","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-08-11T05:10:36Z","receivedAt":"2010-08-11T05:10:36Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi Thomas,\n\nThomas Koch wrote:\n\n> Before I continue with my current design, I wanted to have a look at git \n> notes, whether it would provide better mechanisms then tracking my meta \n> informations in a hidden background branch. (Much like pristine-tar does.)\n\n“git notes” associates arbitrary data to specific objects (blobs, trees,\ncommits, annotated tags).  If your metainformation is per-branch rather\nthan per-commit, then notes will probably not help you.\n\nFeel free to be inspired by their design, though. :)\n\nRegards,\nJonathan\n"},{"id":"147753","messageId":"201008111152.03982.johan@herland.net","threadId":"24688","inReplyTo":"201008101040.07172.thomas@koch.ro","subject":"Re: git notes primer?","fromName":"Johan Herland","fromEmail":"johan@herland.net","sentAt":"2010-08-11T09:52:03Z","receivedAt":"2010-08-11T09:52:03Z","isPatch":false,"sender":{"key":"johan@herland.net","avatar":"https://avatars.githubusercontent.com/u/547031?v=4"},"body":"On Tuesday, August 10, 2010 10:40:06 am Thomas Koch wrote:\n> Hi,\n> \n> I'm working on a patch management system as topgit, but without the\n> complexity:\n> http://koch.ro/blog/index.php?/archives/139-tnt-is-not-topgit.html\n> \n> Before I continue with my current design, I wanted to have a look at git\n> notes, whether it would provide better mechanisms then tracking my meta\n> informations in a hidden background branch. (Much like pristine-tar does.)\n> \n> However I couldn't get a grip on git notes:\n> \n> - Is git notes the only command that works on notes?\n\nPrimarily, yes, although there are some exceptions:\n\n- There is a special fast-import command for quickly building notes trees\n\n- There is some code in log/rev-list for displaying notes\n\n- Recently, commands like 'rebase' and 'commit --amend' have learned options \nto enable copying of notes from the original object to the rewritten object\n\nThere may be more integration between notes and other git commands added in \nthe future.\n\n> - How are notes saved inside GIT?\n\nNotes are kept in 'notes refs' (refs/notes/*) which point into a history that \nis separate/disconnected from your \"regular\" commit history. core.notesRef (or \n$GIT_NOTES_REF, or the --ref option to 'git notes') determines which notes ref \nyou're currently working on (defaults to 'refs/notes/commits').\n\nEvery command that manipulates notes adds a commit to your current notes ref. \nThus, you can review your notes editing history by running 'git log' on a \nnotes ref.\n\nThe tree associated with each notes commit has a special form: All tree \nentries are named after the SHA1 of the Git object they annotate. As such, the \nnotes for a given Git object (with a given SHA1 \"1234567890abcdef...\") is \nfound at \"refs/notes/$NOTES_REF:1234567890abcdef...\".\n\nUnfortunately, this doesn't scale when you get thousands of notes, so there is \nsome automatic fan-out happening when the number of notes exceed certain \nthresholds. We then start making subtrees to limit the number of entries at \neach tree level. Your notes objects are then relocated to live at \n\"refs/notes/$NOTES_REF:12/34567890abcdef...\" (note the extra slash), and if \neven more notes are added, more slashes are added to limit the number of \nentries at each level (e.g. \"refs/notes/$NOTES_REF:12/34/56/78/90abcdef...\")\n\nFortunately, this is all encapsulated by the internal notes API (in notes.h/c) \nand by the 'git notes' command, so as long as you use them, you shouldn't need \nto care about the implementation details.\n\n> - Is git notes and it's implementation stable now?\n\nYes, the current APIs and commands are as stable as any other in 'master'. \nHowever, 'git notes' is still a young feature, and expect new functionality to \nbe added in the future. For example, I'm currently working on 'git notes \nmerge' for auto-merging notes trees (needs special code to handle the fan-\nouts). 'git notes merge' is needed so that we can more easily share notes \nbetween repos.\n\n> - Are there any tutorials on workflows with git notes?\n\nNot really. I don't think there are any workflows where git notes is an \nintegral part of the workflow.\n\n> - What different use cases of git notes do you know?\n\n- Extra annotations to commit messages\n\n- Implementing a textconv cache (already done by Jeff King in notes-cache.h/c)\n\n- Notes could be used to communicate bug status changes in a (distributed) bug \ntracker (e.g. adding notes like \"Causes-Bug: #12345\" to a commit, and then \n\"Fixes-Bug: #12345\" to a later bugfix commit)\n\n- Notes could be used to implement a storage backend for a code review system \n(reviews to a given commit are kept as notes on that commit)\n\n- When synchronizing with foreign version control systems (e.g. git-svn), \nnotes could be used to keep track of cross-VCS relations, e.g. adding a \"SVN-\ncommit: #12345\" note to the corresponding Git commit.\n\n- Any other use case where you need to keep some metadata associated with \nobjects in the git database.\n\n> - What use cases triggered the development of git notes in the first place?\n\nAs has already been stated, we wanted to allow extra annotations to be added \nto existing commit messages without rewriting the commit objects.\n\nHope this helps,\n\n\n...Johan\n"}]}