Getting Started

This book will guide you into setting up the josh proxy to serve your own git repository.

NOTE

All the commands are included from the file gettingstarted.t which can be run with cram.

Setting up the proxy

Josh is distributed via Docker Hub, and is installed and started with the following command:

  $ docker run \
  >   --name josh-proxy \
  >   --detach \
  >   --publish 8000:8000 \
  >   --env JOSH_REMOTE=https://github.com \
  >   --volume josh-vol:/data/git \
  >   joshproject/josh-proxy:latest >/dev/null

This starts Josh as a proxy to github.com, in a Docker container, creating a volume josh-vol and mounting it to the image for use by Josh.

Cloning a repository

Once Josh is running, we can clone a repository through it. For example, let's clone Josh:

  $ git clone http://localhost:8000/josh-project/josh.git
  Cloning into 'josh'...
  $ cd josh

As we can see, this repository is simply the normal Josh one:

  $ ls
  Cargo.lock
  Cargo.toml
  Dockerfile
  Dockerfile.tests
  LICENSE
  Makefile
  README.md
  docs
  josh-proxy
  run-josh.sh
  run-tests.sh
  rustfmt.toml
  scripts
  src
  static
  tests
  $ git log -2
  commit fc6af1e10c865f790bff7135d02b1fa82ddebe29
  Author: Christian Schilling <christian.schilling@esrlabs.com>
  Date:   Fri Mar 19 11:15:57 2021 +0100
  
      Update release.yml
  
  commit 975581064fa21b3a3d6871a4e888fd6dc1129a13
  Author: Christian Schilling <christian.schilling@esrlabs.com>
  Date:   Fri Mar 19 11:11:45 2021 +0100
  
      Update release.yml

Cloning a part of the repo

Josh becomes interesting when we want to clone a part of the repo. Let's check out the Josh repository again, but this time let's filter only the documentation out:

  $ cd ..
  $ git clone http://localhost:8000/josh-project/josh.git:/docs.git
  Cloning into 'docs'...
  $ cd docs

Note the addition of :/docs at the end of the url. This is called a filter, and it instructs josh to only check out the given folder.

Looking inside the repository, we now see that the history is quite different. Indeed, it contains only the commits pertaining to the subfolder that we checked out.

  $ ls
  book.toml
  src
  $ git log -2
  commit dd26c506f6d6a218903b9f42a4869184fbbeb940
  Author: Christian Schilling <christian.schilling@esrlabs.com>
  Date:   Mon Mar 8 09:22:21 2021 +0100
  
      Update docs to use docker for default setup
  
  commit ee6abba0fed9b99c9426f5224ff93cfee2813edc
  Author: Louis-Marie Givel <louis-marie.givel@esrlabs.com>
  Date:   Fri Feb 26 11:41:37 2021 +0100
  
      Update proxy.md

This repository is a real repository in which we can pull, commit, push, as with a regular one. Josh will take care of synchronizing it with the main one in a transparent fashion.