GPM <!-- omit in toc -->

A statically linked, native, platform agnostic Git-based Package Manager written in Rust.

• 1. Install
• 2. Background
• 3. Features
• 4. Security
• 5. Build
  • 5.1. Development build
  • 5.2. Release (static) build
• 6. Getting started
  • 6.1. Creating a package repository
  • 6.2. Publishing your first package
  • 6.3. Installing your first package
• 7. Authentication
• 8. Package reference notation
  • 8.1. Package name
    • 8.1.1. Shorthand notation
    • 8.1.2. URI notation
  • 8.2. Package version
    • 8.2.1. SemVer notation
    • 8.2.2. Git refspec notation
• 9. Matching package references
• 10. Working with multiple package repositories
• 11. Logging
• 12. Commands
  • 12.1. update
  • 12.2. clean
  • 12.3. install
  • 12.4. download
• 13. Integrations
  • 13.1. Travis CI
  • 13.2. AppVeyor
  • 13.3. GitLab CI
  • 13.4. GitLab Releases
  • 13.5. GitHub Releases
• 14. FAQ
  • 14.1. Why GPM?
  • 14.2. Why Git? Why not just curl or wget or whatever?
  • 14.3. But Git does not like large binary files!
  • 14.4. Why storing packages as *.tar.gz archives?
• 15. Contributing
• 16. Troubleshooting
  • 16.1. "Failed to authenticate SSH session" error on Windows
• 17. License

1. Install

• Linux: curl -Ls https://github.com/aerys/gpm-packages/raw/master/gpm-linux64/gpm-linux64.tar.gz | tar xvz
• Windows:
  • cmd.exe: curl -Ls https://github.com/aerys/gpm-packages/raw/master/gpm-windows64/gpm-windows64.tar.gz | tar xvzf -
  • PowerShell: $tmp = New-TemporaryFile ; Invoke-WebRequest -OutFile $tmp https://github.com/aerys/gpm-packages/raw/master/gpm-windows64/gpm-windows64.tar.gz ; tar xf $tmp

2. Background

As a software company, we use Git to manage our source code. Thus, we wanted to use the same Git features we know and love to manage the packages built from that source code.

We also use Git-enabled collaborative platforms (GitLab, GitHub, Gitea...) to:

• Build, package and deploy our code using CI/CD.
• Authenticate and authorize clients to report issues and manage projects.

And we wanted to leverage those collaborative features to effortlessly distribute packages to authorized users.

Introducing GPM: the Git-based Package Manager.

GPM is a platform-agnostic package manager leveraging Git capabilities to store, install and update packages. Thanks to GPM:

• Any Git repository becomes a package repository.
• Any Git-powered collaborative platform (GitLab, GitHub, Gitea...) becomes a package management and distribution platform.

3. Features

• Free, open source and decentralized package management
• 100% backed by the Git protocol
• Fully compatible with the Git ecosystem (GitLab, GitHub, Gitea...):
  • commit and manage packages via your favorite Git client
  • authentication (password, private key, deploy key, deploy token...)
  • commit packages via Git in CI pipelines
  • protected package version branches/tags
  • release page integration (ex: GPM binary package releases)
  • Git LFS support
  • release notes via Git tag messages
• Distribute any package for any platform as a simple *.tar.gz archive
• Semver support
• Public package repositories
• Private package repositories with authentication:
  • username/password, deploy token
  • SSH private key, deploy key
• Modern, intuitive and clean CLI interactive mode
• Non-interactive mode for automation/deployments
• Transparent SSH config (~/.ssh/config) discovery for authentication
• Support for all the common Git protocols (HTTP(s), SSH...)
• Security backed by standard libraries (libgit2, libssh2, OpenSSL...)
• Lightweight (<2,5Mo) fully static 0 dependency binary
• Cross-platform: Windows, Linux, Android (Termux), macOS (untested)
• One-liner installation
• Local cache to speedup package discovery and matching

4. Security

GPM leverages other standard well maintained open source libraries for all sensitive operations:

• All Git operations (clone, pull...) are performed using the Rust bindings for libgit2.
• All SSH operations (Git LFS authentication) are performed using the Rust bindings for libssh2.
• All SSL operations (HTTPS, SSH key management) are performed using the Rust bindings for OpenSSL.

5. Build

5.1. Development build

Dependencies:

• OpenSSL

cargo build

5.2. Release (static) build

Dependencies:

• Docker

docker run \
    --rm -it \
    -v "$(pwd)":/home/rust/src \
    -v "/home/${USER}/.cargo":/home/rust/.cargo \
    ekidd/rust-musl-builder \
    cargo build --release --target x86_64-unknown-linux-musl

6. Getting started

6.1. Creating a package repository

1. Create a Git LFS enabled Git repository, for example a GitHub or GitLab repository.
2. Install Git LFS on your local computer.
3. Clone the newly created repository on your local computer:

git clone ssh://path.to/my/package-repository.git
cd package-repository

4. Enable Git LFS tracking for *.tar.gz files:

git lfs track "*.tar.gz"

5. Add, commit and push .gitattributes:

git add .gitattributes
git commit .gitattributes -m "Enable Git LFS."
git push

Voilà! You're all set to publish your first package!

6.2. Publishing your first package

In this example, we're going to create a simple hello-world package and publish it.

1. Make sure you are at the root of the package repository created in the previous section.
2. Create and enter the package directory:

mkdir hello-world && cd hello-world

3. Create the hello-world.sh script:

echo "#/bin/sh\necho 'Hello World!'" > hello-world.sh

4. Create your package archive:

tar -cvzf hello-world.tar.gz hello-world.sh

5. Add and commit your package archive:

git add hello-world.tar.gz
git commit hello-world.tar.gz -m "Publish hello-world version 0.1.0"

6. Tag your package release with a specific version number:

git tag hello-world/0.1.0

7. Push your new package:

git push
git push --tags

Your hello-world/0.1.0 package is now stored in your package repository and can be installed using gpm!

6.3. Installing your first package

1. Install (or build) gpm.
2. Add your package repository to the gpm sources:

mkdir -p ~/.gpm
echo "ssh://path.to/my/package-repository.git" >> ~/.gpm/sources.list

3. Update the gpm cache:

gpm update

4. Install your package:

gpm install hello-world=0.1.0 --prefix ~/

The version 0.1.0of your hello-world package is now installed and you can run it with sh ~/hello-world.sh.

7. Authentication

gpm will behave a lot like git regarding authentication.

If the repository is "public", then no authentication should be required.

Otherwise, the following authentication methods are supported:

• URL encoded HTTP basic authentication (ex: https://username:password@host.com/repo.git);
• SSH public/private key.

If URL encoded HTTP basic authentication is used, no additional authentication is required. Otherwise, gpm will assume SSH public/private key authentication is used.

Attention: Windows users please read "Failed to authenticate SSH session" error on Windows.

If SSH public/private key authentication is used:

• If the GPM_SSH_KEY environment variable is set to a path that exists/is a file, then its value is used as the path to the SSH private key.
• Otherwise, if gpm can find the ~/.ssh/config file, parse it and find a matching host with the IndentityFile option; then the corresponding path to the SSH private key will be used.
• Otherwise, if gpm can find the ~/.ssh/id_rsa file, it is used as the SSH private key.
• Otherwise, gpm will continue without authentication.

If the SSH private key requires a passphrase, then:

• If the GPM_SSH_PASS environment variable is set/not empty, it is used as the passphrase.
• Otherwise, gpm will prompt the user to type his passphrase.

8. Package reference notation

8.1. Package name

8.1.1. Shorthand notation

This is the most trivial, obvious and simple notation: simply use the package name.

Example:

gpm install my-package

gpm will search by name for the specified package in all the available package repositories. Thus, for s