# Git Tool

Simplify checking out your Git repositories in a structured directory space

Git Tool is a powerful tool for managing your Git repositories, storing them in a consistent folder structure and simplifying access when you need it. One of its biggest advantages is that you no longer need to think about where your development directory is on different devices. Just gt o my-repo and you're ready to start developing, even if the code wasn't already cloned.

# Features

  • Quickly open repositories whether they are already cloned locally or not, using your favourite Git services and a concise folder structure.
  • Launch applications within the context of your repositories quickly and consistently.
  • Weekly scratchpads to help organize random work and doodles with minimal effort.
  • Aliases to make opening your most common repositories as quick as possible.
  • Fast autocompletion on all platforms with support for "sequence search" (ssgt matches SierraSoftworks/git-tool) as found in Sublime and VSCode.

# Example

# Open the sierrasoftworks/git-tool repo in your default app (bash by default)
# This will clone the repo automatically if you don't have it yet.
gt o sierrasoftworks/git-tool

# Open the github.com/sierrasoftworks/git-tool repo in VS Code (if listed in your config)
gt o code github.com/sierrasoftworks/git-tool

# Create a new repository and instruct GitHub to create the repo as well, if you
# have permission to do so.
gt new github.com/sierrasoftworks/demo-repo

# Show info about the repository in your current directory
gt i

# Show information about a specific repository
gt i dev.azure.com/sierrasoftworks/opensource/git-tool

# Open your shell in the current week's scratch directory
gt s
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# Installation

# Step 1: Download the latest Release

Make sure you download the latest releaseopen in new window for your platform and place it in a directory on your $PATH.

WARNING

If you're on Windows, you may need to install the Microsoft Visual C++ Re-distributable package. You can find these on Microsoft's website hereopen in new window. If you are missing this, Git-Tool will not run from the command line and running the binary directly will display an error dialog.

# Step 2: Ensure that you can run git-tool

λ git-tool --version
gt version 1.2.13+1
1
2

# Step 3: Configure your Installation

Add a git-config.yml file somewhere and fill it in with the following (modifying your directory to match your chosen development folder).

---
directory: /home/bpannell/dev
services:
  - domain: github.com
    website: "https://{{ .Service.Domain }}/{{ .Repo.FullName }}"
    httpUrl: "https://{{ .Service.Domain }}/{{ .Repo.FullName }}.git"
    gitUrl: "git@{{ .Service.Domain }}:{{ .Repo.FullName }}.git"
    default: true
    pattern: "*/*"
apps:
  - name: shell
    command: bash
    default: true
  - name: code
    command: code
    args:
      - .
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Then update your environment to inform git-tool of your config file. While you're at it, enable autocomplete.

# Setup Autocomplete

# Windows

notepad $PROFILE.CurrentUserAllHosts
1

Then add the following and save.

# The path to your git-tool config file.
$env:GITTOOL_CONFIG = "C:\dev\git-tool.yml"

# This adds an alias for Git-Tool so you can simply type "gt"
New-Alias -Name gt -Value "git-tool.exe"

# This sets up autocomplete support for git-tool and "gt"
Invoke-Expression (&git-tool shell-init powershell)
1
2
3
4
5
6
7
8

# Linux

vi ~/.bashrc
1

Then add the following:

# ~/.bashrc
export GITTOOL_CONFIG="/your/path/to/git-tool.yml"
alias gt="git-tool"
eval "$(git-tool shell-init bash)"
1
2
3
4

# MacOS

vi ~/.zshrc
1

Then add the following:

# ~/.zshrc
export GITTOOL_CONFIG="/your/path/to/git-tool.yml"
alias gt="git-tool"
eval "$(git-tool shell-init zsh)"
1
2
3
4

# Configuration

# Adding new Services

Git Tool has been written to support a wide range of Git servers and allows you to add your own via the config file.

TIP

You can install services and apps from the registry by running gt config add services/github or gt config add apps/bash. You can get the full list of available apps and services by running gt config list.

# Azure DevOps

services:
  - domain: dev.azure.com
    website: "https://{{ .Service.Domain }}/{{ .Repo.Namespace }}/_git/{{ .Repo.Name }}"
    httpUrl: "https://{{ .Service.Domain }}/{{ .Repo.Namespace }}/_git/{{ .Repo.Name }}"
    gitUrl: "git@ssh.{{ .Service.Domain }}:v3/{{ .Repo.FullName }}"
    pattern: "*/*/*"
1
2
3
4
5
6

# BitBucket

services:
  - domain: bitbucket.org
    website: "https://{{ .Service.Domain }}/{{ .Repo.FullName }}"
    httpUrl: "https://{{ .Service.Domain }}/{{ .Repo.FullName }}.git"
    gitUrl: "git@{{ .Service.Domain }}:{{ .Repo.FullName }}.git"
    pattern: "*/*"
1
2
3
4
5
6

# GitLab

services:
  - domain: gitlab.com
    website: "https://{{ .Service.Domain }}/{{ .Repo.FullName }}"
    httpUrl: "https://{{ .Service.Domain }}/{{ .Repo.FullName }}.git"
    gitUrl: "git@{{ .Service.Domain }}:{{ .Repo.FullName }}.git"
    pattern: "*/*"
1
2
3
4
5
6

# Custom

When adding a custom service, you will need to ensure that you provide the various templates necessary for generating URLs as well as the glob pattern which will be used to identify repositories within the service's development directory. In the case of most Git services, this will be */* (corresponding to the organization name and repository name); however some services like Azure DevOps make use of different patterns.

# Adding new Apps

Git Tool has the ability to launch applications within the context of your repositories. This is useful when you want to quickly open a shell or your favourite editor and start working, however you can also add a wide range of other applications there. Here are a few examples.

# Admin PowerShell on Windows

apps:
  - name: admin
    command: powershell.exe
    args:
      - "Start-Process"
      - "powershell.exe"
      - "-Verb runas"
      - "-ArgumentList"
      - "@('-NoExit', '-Command', 'cd ''{{ .Target.Path }}''')"
1
2
3
4
5
6
7
8
9

# Windows Explorer

apps:
  - name: explorer
    command: explorer.exe
    args:
      - .
1
2
3
4
5

# Aliases

For your most common repositories, it can often make sense to give distinct aliases. These aliases allow you to quickly and exactly specify a repository without typing its full name or relying on autocomplete.

TIP

You can manage aliases by running gt config alias blog github.com/sierrasoftworks/blog.

aliases:
  blog: github.com/sierrasoftworks/blog
1
2

You can use an alias anywhere you would specify a repository name, such as gt o blog.