@b1f6c1c4/hub-sync

Sync your github forks without git in O(1) time, space, and network BW.

Basic usage

1. Install the package with npm (nodejs package manager).

   npm i -g @b1f6c1c4/hub-sync
   

2. Update your fork instantly. For the first time you run this, you will be asked to generate a GitHub Personal Access Token. Follow the instructions carefully and keep your token CONFIDENTIAL.

   hub-sync <name-of-your-fork-repository>
   

Advanced usage

1. Update a certain branch:

   hub-sync <repo>/<branch>
   

2. Update from another user's fork:

   hub-sync <your-repo> <another-user>
   

3. Update from another user's fork, but with a different name:

   hub-sync <your-repo> <another-user>/<repo>
   

4. Update from another user's fork, but with a different name and a different branch:

   hub-sync <your-repo>/<branch> <another-user>/<repo>/<branch>
   

5. Point a branch of your repo to a specific SHA-1: (rarely used)

   hub-sync <your-repo>/<branch> <sha-1>
   

6. Create a new branch:

   hub-sync -c <destination> <source>
   

7. Update even if not fast-forward: (EXTREMELY DANGEROUS)

   hub-sync -f <destination> <source>
   

8. Delete a branch: (EXTREMELY EXTREMELY DANGEROUS)

   hub-sync --delete <destination>
   

9. See hub-sync --help for the complete usage documentation.

Notice: There is NO SAFETY NET at all for -f|--force and -d|--delete. YOU MAY LOSE ALL YOUR WORK ON THAT BRANCH IMMEDIATELY if not used properly. Neither Github nor the author of hub-sync will be responsible for your loss. USE AT YOUR OWN RISK. REFER TO THE LICENSE FOR LEGAL ISSUE.

Technical details

To keep your github fork up-to-date, the old-fashioned way is:

git clone https://github.com/<you>/<repo>
cd <repo>
git remote add upstream https://github.com/<other>/<repo>
git fetch upstream
git push origin upstream/master<master>
cd ..
rm -rf <repo>.git

However, this is totally pointless since you actually download all the data from github.com and upload all the way back. (I know git may be smart enough to upload only what github.com already has, but you have to download everything first.) This approach takes as bad as O(n) time, O(n) space, O(n) network bandwidth.

So the solution is to call Github API directly:

# Assuming you are using HTTPie:
http GET https://api.github.com/repos/<other>/<repo>/git/refs/heads/master
# Find object.sha, and
http PATCH https://api.github.com/repos/<you>/<repo>/git/refs/heads/master "Authorization<token> ..." sha=...
# If branch non-exist, use the following instead
http POST https://api.github.com/repos/<you>/<repo>/git/refs "Authorization<token> ..." sha=...

Now hub-sync does this for you, as smooth as O(1):

# This can be ran everywhere; it works without git.
hub-sync [-f|-c|-d] <you>/<repo>/<branch> <other>/<repo>/<branch>

Wanna take more control over the process, but not to clone everything?

You will need git-get and git-fancy-push. The latter one resolved the long-standing "shallow update not allowed" problem.

git get -g <you>/<repo>
git remote add upstream ...
git fancy-push upstream origin/master:master

License

MIT