Distributed management of git forks

This repository implements distributed management of git forks.

By “forks”, we mean remote repositories which are recorded in the
repository itself, making them easy to share and use.

By storing the collection of forks in the repository, we effectively
define a virtual repository that is composed of all the forks.

This, in turn, lets a repository owner grant contributors fine-grained
permissions on this virtual repository by adding their forks rather
than by giving them permission to push to the main repository.

Since fetching from forks is handled on the client side, no server
side support is required, and contributors can collaborate across
multiple, disjoint git hosting providers.

Disclaimer

This is not an official Google product.

Provided tools

This repository provides two tools for dealing with forks:

1. A git subcommand called “fork” that can be used to add, list,
   and delete entries from the collection of forks.
2. A git remote helper that can be used to pull from all of the
   forks of a repository.

Installation

To install these tools, simply copy the two provided scripts
(git-fork and git-remote-forks) into some directory in your path.

The git-remote-forks tool requires Bash version 4. OSX comes with
version 3 of Bash, so you will have to install the newer version in
order to use the tool on a Mac.

Example usage

Adding a repository with all of its forks as a remote

To add a repository with forks as a remote, append “forks::” to the
repository URL.

For example, to add a remote for the git-appraise repository, with
all of its forks, run:

git remote add origin forks::https://github.com/google/git-appraise

Then, you can pull from all of those forks with the usual
command of git pull origin.

Managing forks

The git fork subcommand is modelled after the remote subcommand.

To list the forks, call git fork with no arguments.

To add a fork, call git fork add, specifying a unique name for
the fork and its URL:

git fork add [-o <OWNER_EMAIL_ADDRESS>]* <NAME> <FETCH_URL>

To remove a fork, call:

git fork remove <NAME>

Finally, since the goal is for the list of forks to be distributed,
you need to be able to push this collection to and pull it from a
remote repository.

To push the collection of forks:

git fork push <REMOTE>

… and to pull them:

git fork pull <REMOTE>

Pushing to the virtual repository through a fork

The virtual repository is read-only. Rather than pushing to it directly,
you push to your fork. Then, anyone pulling from the virtual repository
will fetch the corresponding refs from your fork.

The set of refs fetched from each fork is also stored in the repository.

By default, they are based on the name of the fork and include all branches
and tags that start with <name>/, where <name> is the name of the fork.

For example, if there is a fork named my-fork and it has a branch named
my-fork/my-branch and a tag named my-fork/my-tag, then both that branch
and that tag will appear in the virtual repository.

Additionally, git notes refs from a fork are mapped to the virtual
repository under refs/notes/forks/<fork-name>/.

Finally, all refs from a fork (including branches, tags, and notes)
are mapped to the virtual repository under refs/forks/<fork-name>/.
This ensures that every ref from the fork is accessible via the
virtual repo, even if they do not match one of the rules above.