Registry
Quickly configure Git-Tool by installing configuration snippets maintained by the community.
Writing your own service and application entries can sometimes be a bit more work than we're feeling like and since Git-Tool is meant to make your life easier, not harder, we figured it would be a good idea to try and simplify this part for you as well.
To solve the problem, we added a central registry of config templates which you can search through and install with the gt config add command. This makes the process of setting up your Git-Tool config as easy as doing the following:
1
# Get a list of all the apps and services available to me
2
gt config list
3
4
# Add my favourite apps
5
gt config add apps/powershell
6
gt config add apps/powershell-admin
7
gt config add apps/vscode
8
gt config add apps/visualstudio
9
10
# Add the services I use
11
gt config add services/github
12
gt config add services/azure-devops
Copied!

Browse

To get the latest list of apps and services in the registry, you can always use gt config list straight from your command line. You can also browse the templates on GitHub.

Contributing

Thanks for choosing to contribute to the Git-Tool community :heart:! We'd like to make this as easy as possible, so keep reading for We're so happy that you're considering contributing an app or service config to Git-Tool's registry. In theory, all you need to do is write a yaml file and submit a PR to our [GitHub repo][git-tool] to get it added to the registry folder. We have some automated tests in place which should help ensure that what you are submitting is valid and those run locally as part of the standard Git-Tool test suite (run with cargo test if you have Rust installed).

Registry

Git-Tool's registry is simply a folder hosted on GitHub. Specifically, it's the registry folder in the Git-Tool repo. Within this folder are folders for apps and services to help keep things organized.
For those who prefer a visual representation of what the registry looks like.
1
.
2
└── registry/
3
├── apps/
4
│ ├── bash.yaml
5
→ │ └── your-app.yaml
6
└── services/
7
├── github.yaml
8
→ └── your-service.yaml
Copied!

Example Template

Here is an example of what a registry template might look like and you are welcome to use it as the basis for your own. Keep reading for more information on what each field does and how to use them (or just wing it, if you're already familiar with how Git-Tool's apps and services are defined).
We usually avoid bundling apps and services into a single file, but if you've got a compelling reason to do so - then we can certainly make an exception. The example below includes both apps and services to show how to use them, not because it's a good idea.
1
# yaml-language-server: $schema=https://schemas.sierrasoftworks.com/git-tool/v1/template.schema.json
2
name: Demo
3
description: This is an example of how to create a config template
4
version: 1.0.0
5
configs:
6
# Your config should include either a service (like this)...
7
- platform: any
8
service:
9
domain: github.com
10
website: "https://{{ .Service.Domain }}/{{ .Repo.FullName }}"
11
httpUrl: "https://{{ .Service.Domain }}/{{ .Repo.FullName }}.git"
12
gitUrl: "[email protected]{{ .Service.Domain }}:{{ .Repo.FullName }}.git"
13
pattern: "*/*"
14
15
# Or an app (like this) but usually not both.
16
- platform: windows
17
app:
18
name: shell
19
command: powershell.exe
20
21
# You can also add platform specific versions of each app
22
- platform: linux
23
app:
24
name: shell
25
command: pwsh
Copied!

Template Structure

Registry templates are yaml files (with the .yaml extension) which Git-Tool will use to update your local config. They have a bit of metadata to explain to humans what they do, but the most important part is the list of configs which tell Git-Tool how to modify your local config file.
We publish a JSONSchema schema for Git-Tool templates which your editor can use to give you autocomplete and automatic validation. To include it, just add the following to the top of your template.
1
# yaml-language-server: $schema=https://schemas.sierrasoftworks.com/git-tool/v1/template.schema.json
Copied!

name

This is the human readable name you wish to give to this template. It doesn't need to match the names given to apps or services contained within, but it usually should be pretty close.
1
name: PowerShell Core
Copied!

description

The description is used to explain to humans what your template will add and why that might be of use to them. If possible, use plain English and assume that the reader will not be familiar with the tool or service you are adding.
1
description: |
2
Launches the PowerShell Core shell as your current user.
3
PowerShell Core must be installed on your platform before use.
4
5
https://github.com/PowerShell/PowerShell/releases
Copied!

version

The version is used to show humans when you have updated this template and it should follow SemVer conventions. Currently Git-Tool doesn't keep track of this field, but in future we may add support for updating the items you have installed from the registry using this field.
1
version: 1.0.0
Copied!

configs

This is where the heart of the template fits in. The configs field is a list (array) of config templates which Git-Tool will apply to your config file. These templates can either be for an app or a service and require that you specify the platform that they support. Keep reading for details on what fields you use within each config.
1
configs:
2
- platform: any
3
app:
4
name: shell
5
command: pwsh
Copied!
configs.*.platform
When describing a config template, you need to provide the platform that it supports. This allows Git-Tool to apply the right template in situations where different platforms require different configuration.
The list of supported platform types includes:
    any will apply to any platform.
    windows will only apply to Windows platforms.
    linux will only apply to Linux platforms.
    darwin will only apply to Mac OS X platforms.
1
configs:
2
- platform: linux
Copied!
configs.*.app
When creating a config template which adds an app, you will use the app field to provide an application definition as you would in your normal config file. All of the normal app fields are supported.
::: warning If you specify the app field, you will not be able to provide the service field in the same entry. Add a new item to the configs array if you need to do this. :::
1
configs:
2
- app:
3
name: shell
4
command: bash
5
args: [] # Optional
6
environment: [] # Optional
Copied!
configs.*.service
When creating a config template which adds a service, you will use the service field to provide a service definition as you would in your normal config file. All of the normal service fields are supported.
If you specify the app field, you will not be able to provide the service field in the same entry. Add a new item to the configs array if you need to do this.
1
configs:
2
- service:
3
domain: github.com
4
website: "https://{{ .Service.Domain }}/{{ .Repo.FullName }}"
5
httpUrl: "https://{{ .Service.Domain }}/{{ .Repo.FullName }}.git"
6
gitUrl: "[email protected]{{ .Service.Domain }}:{{ .Repo.FullName }}.git"
7
pattern: "*/*"
Copied!

Creating a PR

The easiest way to get started adding a new app or service to the registry is by using the GitHub web editor to create your template and submit a PR.
Fill in the name of your app or service (this is the name people will use to install it, so keep it short but descriptive) and add your template. Once you're done, create a new PR for your change and we'll get to reviewing it for you!

Automated Testing

Our automated test suite on GitHub will check your PR to make sure that your template can be loaded by Git-Tool correctly and will warn you if there are any problems.
You can also run this same test suite locally if you have rust installed on your machine by cloning the Git-Tool repo and running cargo test in it. If you already have Git-Tool set up, this is as easy as:
1
# Replace this with your Git-Tool fork, if you have one
2
gt o github.com/SierraSoftworks/git-tool
3
cargo test
Copied!
Last modified 20d ago