gitpear - 🍐2🍐 transport for git

CLI, Daemon and Remote helper for git. It is based on holepunch for networking and data sharing.

gitpear creates local bare repository in application directory (default ~/.gitpear/<repository name>), adds it as a git remote in corresponding repository with name pear. So just like in traditional flow doing git push origin, here we do git push pear. Upon each push gitpear regenerates pack files that are shared in ephemeral hyperdrive.

To enable clone or fetch or pull using git <clone|fetch|pull> pear:<public key>/<repo name>. It implements git remote helper that uses hyperswarm for networking in order to directly connect to peer. After connection is initialized it sends RPC request to retrieve list of repositories, clone corresponding pack files and unpack them locally.

Installation

It is necessary for corresponding binaries to be in $PATH, thus gitpear needs to be installed globally. NOTE: application home directory will be created in ~/.gitpear - this may require sudo.

From git

git clone git@github.com:dzdidi/gitpear.git
cd gitpear
npm install
npm link

From git + Nix

git clone git@github.com:dzdidi/gitpear.git
cd gitpear
npm install
npm nix

See ./result - for binaries build by nix. To make the available add to path by running PATH="${PATH:+${PATH}:}${PWD}/result/bin/"

Running

All data will be persisted in application directory (default ~/.gitpear). To change it. Provide environment variable GIT_PEAR

• git pear daemon <-s, --start | -k, --stop> - start or stop daemon
• git pear key - print out public key. Share it with your peers so that they can do git pull pear:<public key>/<repo name>
• git pear init [-s, --share] <path> - It will create bare repository of the same name in application directory (default ~/.gitpear/). It will add git remote in current repository with name pear. So just like in traditional flow doing git push orign, here we do git push pear. By default repository will not be shared. To enable sharing provide -s or call gitpear share <path> later
• git pear share <path> - makes repository sharable
• git pear unshare <path> - stop sharing repository
• git pear list [-s, --shared] - list all or (only shared) repositories

ACL (for authenticated access to enable support of PUSH)

Support of push capabilities only enabled for authenticated users. Currently supported authentication is based on NIP98. To start daemon with authenticated support provile environment varibales GIT_PEAR_AUTH with value nip98 and GIT_PEAR_AUTH_NSEC with value of your NIP19 nsec. For example:

GIT_PEAR_AUTH=nip98 GIT_PEAR_AUTH_NSEC=nsec.... git pear daemon -s 

To manage access to repository use one or combination of the following commands, if path is not provide the command will be executed in the current directory. For userId use NIP19 npub.

• git pear acl [command] <path> - ACL managegement
• git pear acl list [userId] <path> - list repository visitbility and user's role (or roles of all users if userId is not provided)
• git pear acl add <userId:role> <path> - add user as a "role" to repository, available roles are viewer, contributor, admin. Roles exaplained:
  • viewer - can read all branches;
  • contributor - can edit all branches except protected (default master)
  • admin - can edit protected branches
• git pear acl remove <userId> <path> - revoke use access to repository

Branch protection rules

It is possible to setup basic branch protection rules (master is proteted by default).

• git pear branch, same as git pear branch list . - list protection rules
• git pear branch add <branch name> <repo path> - mark branch as protected (defatul repo path is ".")
• git pear branch remove <branch name> <repo path> - unmark branch as protected

Examples of usage

Un authenticated usage example (no push)

Collaboration is possible with the following flow between Alice and Bob in a pure peer-to-peer manner of git.

1. Both Alice and Bob have gitpear installed and Alice wants Bob to help her with repo Repo
2. Alice steps are:

cd Repo
git pear init -s
git pear list
# outputs:
# Repo    pear://<Alice public key>/Repo

3. Bob's steps:

git clone pear://<Alice public key>/Repo
cd Repo
git pear init -s
git checkout -b feature
# implement feature
git commit -m 'done'
git push pear feature
git pear list 
# outputs:
# Repo    pear://<Bob public key>/Repo

4. Alice's steps

git checkout master
git remote add bob pear://<Bob public key>/Repo
git fetch bob
git pull
git merge feature
git push pear master

5. Bob's steps are

git checkout master
git fetch origin
git pull

Authenticated usage example (push) - at your own risk

Collaboration is possible with the following flow between Carol and David in a pure peer-to-peer manner of git.

Carol steps (as a server of code)

1. Start daemon

• GIT_PEAR_AUTH_NSEC=<Carol's nsec> GIT_PEAR_AUTH='nip98' git pear daemon -s

2. Go to repository

• cd repo

3. Initialize git pear repository

• git pear init .

4. Share repository wit hviben visibility () - (default is public)

• git pear share . <private|public>

5. Add Daviv as a contirbutor.
6. List David's npub as a contributor

• git pear acl add <David npub>:contributor

7. Retreive repo url and share it with Dave

• git pear list -s

Dave side (a collaborator for code)

1. Start daemon. This will be needed later for push. Not that no auth or sec are provided which means that push to this place will not be supportedd.

• git pear daemon -s

2. Clone repository. Authorization data and type are necesary for server (Carol) to grant corresponding access persmissions

• GIT_PEAR_AUTH_NSEC=<David's nsec> GIT_PEAR_AUTH='nip98' git clone pear://<Carol's url>/<repo name>

3. Do the necessary change in separate branch

• git checkout -b feat/david
• do change
• git add .
• git commit -s -m 'made by David'

4. Push branch to origin

• GIT_PEAR_AUTH_NSEC=<David's nsec> GIT_PEAR_AUTH='nip98' git push origin feat/david

Carol steps

1. For Carol the changes will arrive as branch feat/david into her pear

• git fetch pear

2. From there she can do

• git diff pear/feat/david or git pull pear feat/david ... merge to master and push to pear