Git-Tool's main purpose is managing your local development directory, ensuring that your repositories are kept organized and are available when you need them with a minimum amount of cognitive effort on your part.
Git-Tool uses a directory structure very similar to
GOPATH. If you're curious why we've chosen this approach, please read my blog post on the topic. If you are simply curious what that means, here's an example:
The first place you're likely to start with Git-Tool is opening a repo you want to work on. To do so, you'll use the
gt open command, which allows you to launch a shell (or any other app you have defined in your config) inside that repository's directory.
Aliases take precedence over repos, which take precedence over apps. When specifying an app, it should appear before the repo/alias parameter to avoid confusion.
New applications can be configured either by making changes to your configuration, or by using the
git-tool config add command to install them from the GitHub registry. For example, you can use
gtconfig add apps/bash to configure
bash as an available app.
--createv2.1+ will create a new repository if one with this name doesn't exist locally.
--no-create-remotev2.1+ will disable the creation of a remote repository when run with
# Open a repository in your default application gt o gh:SierraSoftworks/git-tool # Open a Visual Studio shell in the current repository gt o vs # Open a repository in VS Code gt o gh:SierraSoftworks/git-tool code
If you are already inside a repository, you can specify only an app and it will launch in the context of the current repo, like
gt o vs in the example above. This can be very useful if the command you wish to run is on the complex end of the spectrum (like launching a Visual Studio developer console).
There's nothing new under the sun, but sometimes we like to build it anyway. If you're starting something new and want a fresh repo for it, the
gt new command is your best friend. It will create and
git init your repo, setup your remote hosting provider (if supported).
Of course, this command has auto-completion support and will suggest valid namespaces for your repository to appear in (such as
github.com/SierraSoftworks/), helping you quickly figure out where your repo should be created.
--no-create-remotev2.1+ will disable the creation of a remote repository.
--no-check-existsv3.3+ will disable checking if the repository already exists.
--openv2.1+ will open this repository in your default application once it has been created. You can make this behaviour the default with the
# Create a new repository gt n gh:notheotherben/demo # Create (and open) a new repository gt n --open gh:notheotherben/demo # Create a new repository but don't create it remotely gt n --no-create-remote gh:notheotherben/demo
If you're trying to get a list of your repositories, Git-Tool has you covered. The
gt list command will show you all of your locally cloned repositories and can be a useful tool if you need to (for example) write a script which performs a task across all of them.
If you are migrating machines and want to clone your repositories, you can dump them with
gt list -q and then use
gt clone to import them.
--quietwill limit the output to only the repository's name. This output is useful for consumption by scripts.
--fullwill print out a series of YAML documents, using
---document separators, which contain detailed information about each of your repositories.
# List your repositories (and their web addresses) gt ls # List the repository names containing notheotherben gt ls -q notheotherben # Gather detailed information about sierralib repositories gt ls --full gh:SierraSoftworks/sierralib
If you want to get access to some of the detailed information about a repository managed by Git-Tool, including things like the URLs associated with it or the path to the repo, you can use the
gt info command.
# Get information about the current repository gt i # Get information about a specific repository gt i sierrasoftworks/git-tool
You can omit the repository name if you want to get information about your current repo.
gt clone command does everything the
gt open command does, except open an application. If you're trying to quickly clone a list of repositories, such as when you're setting up your new dev-box, this is the command for you.
# Clone a repository into the appropriate folder gt clone gh:SierraSoftworks/git-tool
Git-Tool usually takes care of setting up your git
origin remote, however sometimes you want to rename projects or even entire organizations. To make your life a little bit easier, the
gt fix command will update your git
origin remote to reflect the current repo information shown in
gt info (which is based on its filesystem path).
--allwill fix any repositories which match the provided pattern.
# Fix the git remote configuration for a single repository gt fix gh:SierraSoftworks/git-tool # Fix the git remote configuration for a group of repositories gt fix --all gh:SierraSoftworks/
The quickest way to update a repo's
origin is to
mv $REPO $NEW_REPO and then run
gt fix $NEW_REPO.
gt remove command will remove a repository from your local machine. This is particularly useful since a repository you have opened with
gt open will often have its shell spawned in the directory you are attempting to delete.
# Remove a repository gt remove gh:SierraSoftworks/git-tool