[PATCH] git-notes.txt: Explain how to transfer notes between repos

[PATCH] git-notes.txt: Explain how to transfer notes between repos

[Øyvind A. Holm]

The documentation for git notes did not mention anywhere how to transfer
notes between repositories, create a section that explains this topic.

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

Re: [PATCH] git-notes.txt: Explain how to transfer notes between repos

[Eric Sunshine]

On Wed, Sep 10, 2014 at 9:56 AM, Ø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.
>
> Signed-off-by: Øyvind A. Holm <sunny@sunbase.org>
> ---
> 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

At minimum: s/has be/has to be/

Slightly improved phrasing, perhaps:

    Notes are not transferred, by default, when using the standard
    fetch/push commands, thus must be transferred explicitly.

> +from a particular remote, use

s/use/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

Re: [PATCH] git-notes.txt: Explain how to transfer notes between repos

[Johan Herland]

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

> 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