Gip
Reference for gip-transport: the gip CLI, the git-remote-git+pear remote helper, the git+pear wrapper for npm, and git+pear:// remote URLs.
Gip lets Git push to and fetch from a repository that lives on a Hypercore instead of a server. A remote is a git+pear:// URL; peers find each other through Hyperswarm, and blind peers can keep a repository available while you are offline. This page documents the binaries installed by gip-transport v3.0.0. The repository database underneath is gip-remote.
System support
Desktop only: macOS, Linux, and Windows, on x64 and arm64. Gip is not available on Android or iOS. git must be on the PATH.
Install
Install the standalone binaries with pear install, or with npx pear-install on a machine without Pear:
pear install pear://gipjk71nbuj3zasm4ywczb93zqk5xbfup16c6d5j8w8yeja4ob6onpx pear-install pear://gipjk71nbuj3zasm4ywczb93zqk5xbfup16c6d5j8w8yeja4ob6oThe binaries land in ~/.local/bin on macOS and Linux, and in %LOCALAPPDATA%\Programs\gip\ on Windows. On macOS and Linux, add ~/.local/bin to the PATH if it is not there already. Standalone binaries update themselves over the air; see Updates.
Or install the npm package, which needs Node.js and does not receive over-the-air updates:
npm i -g gip-transportEither way you get three binaries:
| Binary | Purpose |
|---|---|
gip | Create, add, list, delete, and seed repositories, and manage configuration. |
git-remote-git+pear | The remote helper Git runs for git+pear:// URLs. You don't call it directly. |
git+pear | Runs git with file://pear/ URLs mapped to git+pear://, for npm Git dependencies. |
Remote URLs
git+pear://<key>/<name>
git+pear://<fork>.<length>.<key>/<name>
git+pear://<key>/<name>?storage=<dir><key>is the repository's public key, z32-encoded. It is the key of the repository's Hypercore, not yourgip idkey.<name>is the repository name given togip new.<fork>.<length>.is the versioned form thatgip listand every push print. The remote helper reads only<key>and<name>, so a versioned URL still fetches the repository's latest state.?storage=<dir>makes the remote helper use<dir>as its storage directory instead of~/.gip. It is the remote-helper counterpart of--storage.
gip
Manage the repositories in the local store.
gip [flags] [command]Flags go before the command:
--storage <dir>: use<dir>as the storage directory. Default:~/.gip--no-updates: don't check for over-the-air updates during this run.--version, -v: print the version, for examplegip v3.0.0.--help, -h: show help. Every subcommand also takes--help.
With no command, gip prints its help.
gip new
Create a repository that you own and can push to.
gip new <name><name> can hold letters, digits, _, and -; any other name fails with Invalid repository name. Support alphanumeric characters, underscores, and hyphens. The command prints the repository's URL:
Repository my-repo created git+pear://bm541t4dgktjrenytm9izjmttn6hczjbjdeo38h3hu4dzz6hb9ay/my-repoEach repository gets its own key. Creating a repository again under the name of a deleted one gives it a new key, never the old one.
gip add
Add someone else's repository to the local store by URL.
gip add <url><url> must start with git+pear://. The command joins the swarm, waits until it finds a peer that has the repository, and downloads all of it. It then prints added, or already in store if the name was already present, with the block count. After that, gip seed serves the repository along with your own.
You don't need gip add to clone: git clone adds the repository to the store on its own.
gip list
List the repositories in the local store.
gip list [--json]Each line shows the repository's name, block count, connected peers, and versioned URL:
* my-repo 5 blocks · 0 peers · git+pear://0.5.bm541t4dgktjrenytm9izjmttn6hczjbjdeo38h3hu4dzz6hb9ay/my-repoWith --json, it prints one array instead:
[{"name":"my-repo","url":"git+pear://0.5.bm541t4dgktjrenytm9izjmttn6hczjbjdeo38h3hu4dzz6hb9ay/my-repo"}]gip list only reads the local store. It doesn't announce anything on the swarm. With no repositories it prints No repositories, or [] with --json.
gip delete
Remove a repository from the local store.
gip delete <name>The command asks Delete repository <name>? [y/N] and continues only on y or yes. It removes the repository's record, stops announcing it, and clears its blocks locally. Copies that other peers or blind peers already hold are not affected. An unknown name prints Repository <name> not found.
gip seed
Serve every repository in the local store until you stop the process.
gip seedgip seed announces each repository on the swarm as a server, including repositories you only added or cloned, whatever the seed-read-only setting says. It prints your public key and each repository's block count, then logs peers and block transfers:
Seeding — Public key: i1zckagoe1mrzjcngtk7uqn9hi8gkkaaqmgzj1c93e1zwinfyu3y
my-repo — 5 blocks
+ Peer connected 7xk9m3f2
↑ my-repo block 0 → 7xk9m3f2↑ marks a block sent to a peer and ↓ a block received. With no repositories it prints No repositories to seed and exits.
gip id
Print your public key.
gip idThis is the key of the key pair gip uses on the DHT, z32-encoded. Give it to a blind peer operator who needs to recognize your requests. It is not a repository key.
gip config
Read and change configuration. It is stored in the local database under the storage directory.
gip config
gip config get <key>
gip config set <key> <value>
gip config add <key> <value>
gip config remove <key> <value>With no subcommand, gip config prints every key. There are two keys:
| Key | Type | Default | Subcommands | Meaning |
|---|---|---|---|---|
blind-peers | list of z32 keys | none | get, add, remove | Blind peers that mirror your repositories. |
seed-read-only | on or off | on | get, set | Announce repositories you don't own as a server, so peers can fetch them from you, while Git fetches or pushes or gip add runs. |
With blind-peers set, gip registers each repository it opens with the blind peers and asks for two mirrors. gip config add ignores a key that is already in the list, and gip config remove prints Value not found for a key that isn't. gip config get blind-peers prints (not set) for an empty list.
gip config set seed-read-only accepts on, true, yes, or 1, and off, false, no, or 0. Anything else fails with Invalid boolean: <value> (use on|off). An unknown key prints Unknown config key: <key>.
gip config add blind-peers <z32-key>
gip config set seed-read-only offgit-remote-git+pear
Git runs git-remote-<scheme> for any URL whose scheme it doesn't know, so with this binary on the PATH, git+pear:// URLs work with the usual commands:
git remote add origin git+pear://<key>/my-repo
git push origin main
git fetch origin
git clone git+pear://<key>/my-repo
git push origin --delete my-branchBehavior:
- Refs: branches (
refs/heads/*) and tags (refs/tags/*) are supported, including annotated tags. - Push: you can push only to a repository you created with
gip newin the same storage directory. A forced push (git push --force) overwrites the branch. After each push the helper prints the new versioned URL on standard error, asLatest: git+pear://<fork>.<length>.<key>/<name>. - Delete:
git push origin --delete <branch>removes a branch or tag. - Remote
HEAD: after a push, the remote'sHEADpoints at the branch checked out locally, if that branch exists on the remote. - Fetch and clone: the helper joins the swarm, waits for a peer that has the repository, downloads it, and adds it to the local store, as
gip adddoes. - Progress: Git-style progress lines (
Enumerating objects,Writing objects,Receiving objects) go to standard error, so they never mix with the protocol on standard output. - Storage: the helper uses
~/.gip, or the directory in the URL's?storage=parameter. - Updates: set
GIP_NO_UPDATESto any non-empty value to skip the over-the-air update check for one command, for exampleGIP_NO_UPDATES=1 git push.
git+pear
Run git with two extra configuration entries, passed through the GIT_CONFIG_COUNT, GIT_CONFIG_KEY_<n>, and GIT_CONFIG_VALUE_<n> environment variables and appended to any that are already set:
| Key | Value |
|---|---|
url.git+pear://.insteadOf | file://pear/ |
protocol.git+pear.allow | always |
git+pear [git arguments]git+pear exists for npm. npm doesn't accept git+pear:// in a dependency, but it does accept git+file://. It strips the git+ before it calls Git, and the url.git+pear://.insteadOf entry then makes Git rewrite file://pear/<key>/<name> to git+pear://<key>/<name>. To use it, add these lines to the project's .npmrc:
git=git+pear
allow-git=allThen install a repository as a dependency:
npm install git+file://pear/<key>/<name>npm records the dependency as git+file://pear/<key>/<name> in package.json, and the commit it installed in package-lock.json. A versioned link such as git+file://pear/0.32.<key>/<name> installs the latest commit too, because the remote helper ignores the <fork>.<length>. prefix; the commit in package-lock.json is what pins the version. The repository must be reachable: someone has to be seeding it, or a blind peer has to hold it.
Storage
Everything gip keeps on disk lives in one directory: the corestore with every repository, the local database with the repository list and configuration, and the updater's staging area. The default is ~/.gip. Change it with gip --storage <dir> for the CLI, and with ?storage=<dir> in the URL for the remote helper. Point both at the same directory to use the same repositories.
Updates
Standalone binaries installed from the pear:// link update themselves over the air. Each binary replaces itself with the build for its platform from the upgrade drive. The npm package never updates itself.
Updates download only during long-running work: for as long as gip seed runs, and for the duration of a fetch or push. Other gip commands skip the check. A partial download stays in storage and resumes next time. gip seed logs Downloading update, then Update applied — restart to run the new version.
To opt out for one run:
gip --no-updates seed
GIP_NO_UPDATES=1 git pushLibrary
The package also exports GipLocalDB, the local store the CLI and the remote helper share. Its type declaration is any, so treat it as unstable. It accepts { dir, store, swarm, readonly } and opens gip-remote Remote instances by URL:
const { GipLocalDB } = require('gip-transport')
const local = new GipLocalDB()
await local.ready()
const remote = await local.openRemote('git+pear://<key>/my-repo')
console.log(remote.availablePeers)
await local.close()See also
- gip-remote—the repository database Gip stores Git objects in.
- Blind peering—what a blind peer does with the repositories you register.
pear install—installs the standalone binaries.- Hyperswarm—how peers find each repository.
Last updated on