Re: [PATCH] git-notes.txt: Explain how to transfer notes between repos
On Wed, Sep 10, 2014 at 3:56 PM, Øyvind A. Holm <sunny@sunbase.org> wrote:
> The documentation for git notes did not mention anywhere how to transfer
> notes between repositories, create a section that explains this topic.
Thanks! Although there are some online resource containing similar information (e.g. http://git-scm.com/blog/2010/08/25/notes.html), this info has obviously been missing from the manual page for way too long.
Your text illustrates well how to work with simple notes sharing scenarios, where there are typically only a single writer per notes ref. However, if you have a situation where you and your peers are contributing to the same notes refs, then you will need a more sophisticated scheme.
In your current illustration, if you do some notes work on refs/notes/foo, and your friend does the same, then, when you fetch from your friend (with the +refs/notes/*:refs/notes/* refspec configured), their notes work will silently overwrite your own notes work (the '+' in the refspec causes a "forced update"). What you typically would want instead, is to fetch your friend's notes refs into a separate namespace (similar to how git stores remote branches under refs/remotes/$remote/* instead of directly under refs/heads/*), so that you can examine their changes before potentially merging them with your own (using 'git notes merge').
This is a more complicated workflow than the one you sketch out below, and although it's only really needed for notes ref with multiple writers, I believe that is such a common use case that it merits at least a mention in the manual page. I'm not sure if we would need to sketch out the entire workflow, or whether it's sufficient to merely mention that a more complicated workflow is needed in the multi-writer case.
Have fun! :)
...Johan
Show 62 quoted lines
> Signed-off-by: Øyvind A. Holm <sunny@sunbase.org>
> ---
> Documentation/git-notes.txt | 39 +++++++++++++++++++++++++++++++++++++++
> 1 file changed, 39 insertions(+)
>
> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
> index 310f0a5..4237bec 100644
> --- a/Documentation/git-notes.txt
> +++ b/Documentation/git-notes.txt
> @@ -264,6 +264,45 @@ prior to the merge, these will also be removed by this notes merge
> strategy.
>
>
> +TRANSFERRING NOTES ACROSS REPOSITORIES
> +--------------------------------------
> +
> +Notes are not transferred by default when using the standard
> +fetch/push commands, but has be done explicitly. To fetch all notes
> +from a particular remote, use
> +
> +------------
> +$ git fetch origin refs/notes/*:refs/notes/*
> +------------
> +
> +`git fetch` can be configured to automatically fetch notes from a
> +remote with this command:
> +
> +------------
> +$ git config --add remote.origin.fetch +refs/notes/*:refs/notes/*
> +------------
> +
> +To transfer notes to a remote repository:
> +
> +------------
> +$ git push origin refs/notes/*
> +------------
> +
> +If you don't want to fetch or push all notes stored under
> +`refs/notes/`, replace the asterisk with the specific type of notes
> +you want to transfer:
> +
> +------------
> +$ git fetch origin refs/notes/commits:refs/notes/commits
> +------------
> +
> +or
> +
> +------------
> +$ git push origin refs/notes/commits
> +------------
> +
> +
> EXAMPLES
> --------
>
> --
> 2.1.0.127.g0c72b98
>
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at http://vger.kernel.org/majordomo-info.html
--
Johan Herland, <johan@herland.net>
www.herland.net
Øyvind A. Holm
