Make it straightforward and discoverable for two people to share git-integration instructions about git-integration

[matthewlmcclure]

I was able to share the instructions between two repositories. For others:

To push from your repository clone to a remote:

$ git push origin refs/insns/*

To fetch from a remote such as GitHub:

$ git fetch origin 'refs/insns/*:refs/insns/*'

[johnkeeping]

There's a note at the end of the manpage, but it assumes quite a lot of Git knowledge. Suggestions for improvements welcome... 😃

[sschuberth]

How about just adding two new options --push-insns and --fetch-insn (or ...-instructions) that do exactly that? If no argument to the options is specified, instructions for all integration branches should be pushed / fetched, otherwise only for the given integration branch name.

[johnkeeping]

The setup I use is either to force push everything (including instructions) when I own the remote repository or to use a pre-push hook when I'm using a shared remote. The setup for pushing everything is:

git config remote.pushdefault my-remote
git config push.default matching
git config --add remote.my-remote.push +refs/insns/*:refs/insns/*
git config --add remote.my-remote.fetch +refs/insns/*:refs/insns/*

And for a pre-push hook is:

git config --add remote.origin.fetch +refs/insns/*:refs/insns/*
cat <<\EOF >.git/hooks/pre-push
#!/bin/sh
while read -r lref lsha1 rref rsha1
do
    case "$lref" in
    refs/heads/*)
        if git rev-parse --quiet --verify refs/insns/${lref#refs/heads/} >/dev/null
        then
            git push origin +refs/insns/${lref#refs/heads/}:refs/insns/${lref#refs/heads/}
        fi
    esac
done
EOF

All of that assumes that you start with something up-to-date and that no one else will change the remote instruction sheet, which isn't really ideal. So perhaps a --pull-insns option that merges remote changes with local changes would be useful (at which point --push-insns becomes a natural extension); at that point I think we will also need to store the remote refs separately, so unless Git makes the change to have refs/remotes/<name>/heads/ instead of just refs/remote/<name>/ we'll need something like refs/remote-insns/<remote>/ to store the remote version.

Perhaps that means that the first new option should be --merge-insns-into <other> which updates refs/insns/<name> with the result of merging refs/insns/<name> into <other> (so it performs a "backwards" merge, which I think is normally the right way round when pulling - there's been a lot of discussion about this on the Git mailing list over the last few months).

[matthewlmcclure]

I wonder if there's a good way to make the instructions part of the commit
that results from git integration --rebuild. I haven't completely thought
it through, but it seems plausible that it might feel more natural to
couple the instructions and the resulting branch.

[johnkeeping]

Interesting. I wonder if it would be useful to use notes to attach integration instructions to the resulting commits. That might make the status operation for some more complicated scenarios (e.g. fixup commits to create evil merges) easier, but it would be yet another thing to share with shared integration branches.

[matthewlmcclure]

I'm not very familiar with Notes.

I had been thinking of some way to attach a hidden Blob of instructions to a Commit. I imagine that might not work well if it meant I could inadvertently destroy the instructions by rewinding or similar.

[johnkeeping]

For attaching extra data to commits, notes are pretty much the way to go. But you're right that they may not be preserved across various operations (see the documentation on notes.rewriteRef in git-notes(1)).

I think I'm veering off into an unrelated topic now though, since adding yet another ref won't make it easier to share instruction sheets! (I should have read the subject, not just the latest comment...)

I'm not convinced that there is a technical solution for discovering instruction sheets, but perhaps git-integration could try to fetch instructions from a remote if a user tries to use it on a branch that doesn't have instructions; that probably wants to be configurable and default to "ask".

[matthewlmcclure]

Something like that might work.