Git Bundle Server

Background

By running this software, you can self-host a bundle server to work with Git's bundle URI feature.

This repository is under active development, and loves contributions from the community :heart:. Check out CONTRIBUTING for details on getting started.

Getting Started

Installing

:warning: Installation on Windows is currently unsupported :warning:

Linux

Debian packages (for x86_64 systems) can be downloaded from the Releases page and installed with:

sudo dpkg -i /path/to/git-bundle-server_VVV-RRR_amd64.deb

# VVV: version
# RRR: package revision

MacOS

Packages for both Intel and M1 systems can be downloaded from the Releases page (identified by the amd64 vs arm64 filename suffix, respectively). The package can be installed by double-clicking the downloaded file, or on the command line with:

sudo installer -pkg /path/to/git-bundle-server_VVV-RRR_AAA.pkg -target /

# VVV: version
# RRR: package revision
# AAA: platform architecture (amd64 or arm64)

From source

To avoid environment issues building and executing Go code, we recommend that you clone inside the src directory of your GOROOT.

You can also install the bundle server application from source on any Unix-based system. To install to the system root, clone the repository and run:

$ make install

Note that you will likely be prompted for a password to allow installing to root-owned directories (e.g. /usr/local/bin).

To install somewhere other than the system root, you can manually specify an INSTALL_ROOT when building the install target:

$ make install INSTALL_ROOT=</your/install/root>

Uninstalling

From Debian package

To uninstall git-bundle-server if it was installed from a Debian package, run:

$ sudo dpkg -r git-bundle-server

Everything else

All other installation methods include an executable script that uninstalls all bundle server resources. On MacOS & Linux, run:

$ /usr/local/git-bundle-server/uninstall.sh

Usage

Repository management

The following command-line interface allows you to manage which repositories are being managed by the bundle server.

• git-bundle-server init <url> [<route>]: Initialize a repository by cloning a bare repo from <url>. If <route> is specified, then it is the bundle server route to find the data for this repository. Otherwise, the route is inferred from <url> by removing the domain name. For example, https://github.com/git-for-windows/git is assigned the route git-for-windows/git. Run git-bundle-server update to initialize bundle information. Configure the web server to recognize this repository at that route. Configure scheduler to run git-bundle-server update-all as necessary.

• git-bundle-server update [--daily|--hourly] <route>: For the repository in the current directory (or the one specified by <route>), fetch the latest content from the remote and create a new set of bundles and update the bundle list. The --daily and --hourly options allow the scheduler to indicate the timing of this instance to indicate if the newest bundle should be an "hourly" or "daily" bundle. If --daily is specified, then collapse the existing hourly bundles into a daily bundle. If there are too many daily bundles, then collapse the appropriate number of oldest daily bundles into the base bundle.

• git-bundle-server update-all [<options>]: For every configured route, run git-bundle-server update <options> <route>. This is called by the scheduler.

• git-bundle-server stop <route>: Stop computing bundles or serving content for the repository at the specified <route>. The route remains configured in case it is reenabled in the future.

• git-bundle-server start <route>: Start computing bundles and serving content for the repository at the specified <route>. This does not update the content immediately, but adds it back to the scheduler.

• git-bundle-server delete <route>: Remove the configuration for the given <route> and delete its repository data.

• git-bundle-server list [<options>]: List each route and associated information (e.g. Git remote URL) in the bundle server.

• git-bundle-server repair routes [<options>]: Correct the contents of the internal route registry by comparing to bundle server's internal repository storage.

Web server management

Independent of the management of the individual repositories hosted by the server, you can manage the web server process itself using these commands:

• git-bundle-server web-server start: Start the web server process.

• git-bundle-server web-server stop: Stop the web server process.

Finally, if you want to run the web server process directly in your terminal, for debugging purposes, then you can run git-bundle-web-server.

Additional resources

Detailed guides to more complex administration tasks or user workflows can be found in the docs/tutorials directory of this repository.

Local development

Building

To avoid environment issues building and executing Go code, we recommend that you clone inside the src directory of your GOROOT.

In the root of your cloned repository, you can build the git-bundle-server and git-bundle-web-server executables a few ways.

The first is to use GNU Make; from the root of the repository, simply run:

$ make

If you do not have make installed on your system, you may instead run (again from the repository root):

$ go build -o bin/ ./...

Testing and Linting

Unless otherwise specified, run commands from the repository root.

Unit tests

go test -v ./...

Linter

go vet ./...

End-to-end tests

In order to run these tests, you need to have a recent version of Node.js (current LTS version is a pretty safe bet) and NPM installed.

For the standard set of tests (i.e., excluding exceptionally slow tests), run:

make e2e-test

To configure the test execution and filtering, set the E2E_FLAGS build variable. The available options are:

• --offline: run all tests except those that require internet access.
• --all: run all tests, including slow performance tests.

The above modes are mutually exclusive; if multiple are specified, only the last will be used. For example, E2E_FLAGS="--offline --all" is equivalent to E2E_FLAGS="--all".

:warning: The performance tests that are excluded by default clone very large repos from the internet and can take anywhere from ~30 minutes to multiple hours to run, depending on internet connectivity and other system resources.

License

This project is licensed under the terms of the MIT open source license. Please refer to LICENSE for the full terms.

Maintainers

See CODEOWNERS for a list of current project maintainers.

Support

See SUPPORT for instructions on how to file bugs, feature requests, and general questions/requests for help.