12 releases (6 breaking)
0.7.1 | Oct 22, 2023 |
---|---|
0.7.0 | Sep 22, 2023 |
0.6.0 | Oct 10, 2022 |
0.5.0 | Jan 15, 2022 |
0.1.1 | May 30, 2021 |
#101 in Development tools
27 downloads per month
125KB
3K
SLoC
git-nomad
Synchronize work-in-progress git branches in a light weight fashion. Motivation:
- You frequently work on the same repository from multiple machines, like a laptop and a desktop.
- You frequently rewrite history and use short understandable-by-only-you branch names, making pushing regular branches to git remotes cumbersome.
- You want all the efficiency and synchronization benefits of having a git clone available, meaning external syncing tools like Dropbox or network mounts are right out.
- You want this synchronization to work out-of-the-box with popular third party remote hosts like GitHub.
Usage
Install git-nomad
to make it available on your $PATH
.
Assume you're hacking away with your usual git workflow:
rraval@desktop:~/git-nomad$ git checkout -b feature
rraval@desktop:~/git-nomad$ touch new_file
rraval@desktop:~/git-nomad$ git add .
rraval@desktop:~/git-nomad$ git commit -m "new file"
Whenever you like, you can push the state of your local branches with:
# Synchronizes with a remote called `origin` by default.
# See `--help` for overriding this explicitly.
rraval@desktop:~/git-nomad$ git nomad sync
Pushing local branches to origin... 3s
Fetching branches from origin... 0s
Listing branches at origin... 3s
desktop
refs/nomad/desktop/feature -> c340cd55853339e4d039746495cdb80cd9e46123
refs/nomad/desktop/master -> 267719fb8448cc1cbef2c35a638610573779f2ac
At some future point, you wish to pick up development on a different machine:
rraval@laptop:~/git-nomad$ git nomad sync
Pushing local branches to origin... 2s
Fetching branches from origin... 1s
Listing branches at origin... 2s
desktop
refs/nomad/desktop/feature -> 1a101799507ba67d822b97105aafa0ac91ce5183
refs/nomad/desktop/master -> 267719fb8448cc1cbef2c35a638610573779f2ac
laptop
refs/nomad/laptop/master -> 267719fb8448cc1cbef2c35a638610573779f2ac
Which prints out refs to use to pick up where you left off:
rraval@laptop:~/git-nomad$ git checkout -b feature refs/nomad/desktop/feature
# Hack away where you left off on desktop
Let's say that the laptop
machine is where development is happening now, so
you go back to desktop
to throw away the now outdated branch:
rraval@desktop:~/git-nomad$ git checkout master
rraval@desktop:~/git-nomad$ git branch -D feature
Deleted branch feature (was 1a10179).
rraval@desktop:~/git-nomad$ git nomad sync
Pushing local branches to origin... 2s
Fetching branches from origin... 1s
Listing branches at origin... 0s
Pruning branches at origin... 0s
Delete refs/nomad/desktop/feature (was 1a101799507ba67d822b97105aafa0ac91ce5183)... 0s
desktop
refs/nomad/desktop/master -> 267719fb8448cc1cbef2c35a638610573779f2ac
laptop
refs/nomad/laptop/feature -> dedf3f9d3ad279a401877b351c3ec13aa47cbbd4
refs/nomad/laptop/master -> 267719fb8448cc1cbef2c35a638610573779f2ac
If you'd like to stop using git-nomad
and clean up all the refs it has created:
# See also the `purge --host` option.
rraval@desktop:~/git-nomad$ git nomad purge --all
Fetching branches from origin... 1s
Listing branches at origin... 0s
Pruning branches at origin... 2s
Delete refs/nomad/desktop/master (was 267719fb8448cc1cbef2c35a638610573779f2ac)... 0s
Delete refs/nomad/laptop/feature (was dedf3f9d3ad279a401877b351c3ec13aa47cbbd4)... 0s
Delete refs/nomad/laptop/master (was 267719fb8448cc1cbef2c35a638610573779f2ac)... 0s
How it works
Git is unabashedly a content-addressed filesystem that manipulates blob
, tree
, and commit
objects. Layered on top of this is a half decent version control system, though this claim is contentious at best.
Git branches are implemented on top of a more general scheme called refs
, where the local branch master
is simply the commit pointed to by refs/heads/master
. Git reserves a few hierarchies for its own use:
refs/heads/*
represent local branches.refs/tags/*
represent tags.refs/remotes/*
represent remote branches.
git-nomad
works directly with refs to implement its own light weight synchronization scheme:
- Push local
refs/heads/*
to remoterefs/nomad/{user}/{host}/*
. This allows multiple users on multiple hosts to all usegit-nomad
on the same remote without overwriting data. - Fetch remote
refs/nomad/{user}/*
to localrefs/nomad/*
. This makes all the host refs for a given user available in a local clone. - Prune local
refs/nomad/*
refs where the corresponding branch has been deleted.
Using refs like this has advantages:
- You only pay the storage cost for the content unique to the branch. The bulk of repository history is shared!
- As refs get cleaned up,
git
s automatic garbage collection should reclaim space. - Since these refs are under a separate
refs/nomad
hierarchy, they are not subject to the usual fast-forward only rules.
Installation
On Linux or Mac OS X
Releases on GitHub have prebuilt binary assets: https://github.com/rraval/git-nomad/releases
- Download the latest version for your OS.
gunzip
the downloaded file.- Place the binary somewhere in your
$PATH
. - Check that things work with
git nomad --version
.
On NixOS / via Nix
Install via nixpkgs:
$ nix-env --install git-nomad
From source
If you have cargo
available:
$ cargo install git-nomad
Bleeding Edge
Via nix run
Nix can build and run the binary directly from GitHub via:
$ nix run github:rraval/git-nomad
Contributing
There are a few ways to make this project better:
- Try it and file issues when things break. Use the
-vv
flag to capture all information about the commands that were run. - Build packages for various operating systems.
Dependencies
~6–16MB
~203K SLoC