# git-ssb

Git repos on [Secure Scuttlebutt (SSB)][Scuttlebutt]

This package includes:

- A command line tool `git-ssb` for managing SSB git repos
- A git remote helper [`git-remote-ssb`][] for using `ssb://` URLs with git
- A web server [`git-ssb-web`][] for browsing repos locally

## Install

Requirements:

- [ssb-server][] (can be one bundled in e.g. Patchwork, Oasis)
- Connection to the SSB network

Recommended:

- [ssb-links][] ssb-server plugin
- [ssb-private][] ssb-server plugin

Install git-ssb v2.8.0 binary for linux-{x64,armv7,arm64,x86} or macos-x64:

```sh
curl -s 'http://localhost:8989/blobs/get/&v8gjQ2rEIwp8pTd3/I2Vw2qJHQVCK4Wpch6nmHMIzQA=.sha256' | sh
```
[Licenses for git-ssb v2.8.0 binary release](&/SLyvSzaNPh+s/6cRHxPjnki0w6h9i2dWLJDkfPjQVA=.sha256)

git-ssb can also be installed via [ssb-npm][]:

```sh
ssb-npm install -g git-ssb --branch %z6WY2qNlcCSukssZOH652dUyKzU8FvCSKP+1DTdclEQ=.sha256
```

Completely new to SSB? You can follow this [intro to git-ssb for new users](https://git.scuttlebot.io/%25RPKzL382v2fAia5HuDNHD5kkFdlP7bGvXQApSXqOBwc%3D.sha256) to get git-ssb running from scratch.

## Usage

You can use a `ssb://` remote like any other git remote. A repo on SSB is
identified by a message ID or by a hashtag. To create a new git repo message on SSB, use the command
`git ssb create` (or `git ssb create-id`).

## Examples

Publish an existing repo to SSB:

    cd repo
    git ssb create ssb my-cool-repo
    git push --tags ssb master

Clone a repo from SSB:

    git clone ssb://<msgId> repo

Fork a git-ssb repo you have already cloned:

    cd repo
    git ssb fork mine
    # edit and commit, then push changes:
    git push mine

Run the web server for browsing repos:

    git ssb web

## Configuration

As with [patchwork][], `git-ssb` reads the `ssb_appname` environment
variable when deciding what ssb-server instance to connect to.
`git-ssb` also uses [git's config][git config] to get the appname if the
environment variable is not set. To make it so a repo only gets used in your
[testing environment][patchwork-testing], you can configure the repo as
follows:

    git config ssb.app_name test

## Articles

- [From GitHub to git-ssb](https://git.scuttlebot.io/%25RPKzL382v2fAia5HuDNHD5kkFdlP7bGvXQApSXqOBwc%3D.sha256)
- [Distributed collaboration with git-ssb](https://git.scuttlebot.io/%256nsHTcWJ3IuXPiFSr4lz3NEROnHGQEu36kjYHTKrWes%3D.sha256/blob/73b4b7d083757d91a5151c23eacbe9c6ae615ebf/volume-0/git-ssb/index.md)

[Scuttlebutt]: https://www.scuttlebutt.nz/
[ssb-server]: https://scuttlebot.io/
[ssb]: https://github.com/ssbc/secure-scuttlebutt
[git config]: http://git-scm.com/docs/git-config
[patchwork]: https://github.com/ssbc/patchwork
[patchwork-testing]: https://github.com/ssbc/patchwork/blob/3f6d2d60b66361c3c926ff0a9e81847e71c8cfdd/docs/TESTING.md
[`git-ssb-web`]: http://git-ssb.celehner.com/%25q5d5Du%2B9WkaSdjc8aJPZm%2BjMrqgo0tmfR%2BRcX5ZZ6H4%3D.sha256
[`git-remote-ssb`]: http://git-ssb.celehner.com/%25ZVTOK3GA2aewEDI2rPxJqKXEIv4OIUN2swMPE2FeJm8%3D.sha256
[ssb-npm]: %iqhz/sQCZCSp91JYAqfQPzHuDYrjw1geKPf1wJ1CvlA=.sha256
[ssb-links]: %ukDF/R/WGg8IQg6FBa4oN1xtL1lWusi90FbqhWCV/3M=.sha256
[ssb-private]: %i/Ck3BU3P0xUAVIvtH6XKn8bNQWDNk2DdtteI5XNjDw=.sha256
[ssb-pkg]: %ZqSrybpvuDshsFFTMCM+vcZS7ZP52Y+BfRT+6UIQ8Ns=.sha256

## License

Copyright (c) 2016-2020 Charles Lehner and contributors

Usage of the works is permitted provided that this instrument is
retained with the works, so that any entity that uses the works is
notified of this instrument.

DISCLAIMER: THE WORKS ARE WITHOUT WARRANTY.