goto

A small Go CLI for marking directories with custom names and jumping back to them, for example goto tt-azure.

goto stores named directory marks and resolves them later. Because a child process cannot change the current directory of your parent shell, goto <name> works through a shell wrapper emitted by goto init <shell>.

gt is a short alias that mimics goto. It is the same program with the same subcommands, and after shell integration is enabled the generated wrapper functions let gt <name> change directories just like goto <name>.

Features

• Cross-platform single Go binary.
• Stores configuration under your home directory in ~/.goto/marks.json.
• Works with bash, zsh, fish, and PowerShell.
• Mark the current directory or any specific path, then jump by name.
• Scan directory trees for git repositories and mark them automatically.
• Shell integration includes wrappers and tab completion for goto and gt.

Installation

Go install

go install github.com/thomas-temby/goto@latest

This installs the goto binary to GOBIN, or to $(go env GOPATH)\bin when GOBIN is not set. Make sure that directory is on your PATH. Use the install scripts below if you want both goto and gt installed automatically.

Build from source

Clone the repository, then build from the repository root:

go build -o goto .
cp goto gt

On Windows, build an .exe:

go build -o goto.exe .
Copy-Item goto.exe gt.exe

Move the resulting goto and gt binaries to a directory on your PATH.

Install scripts

This repository includes install scripts that build from source and copy the binary to a user-local install directory.

• install.sh for macOS/Linux:
  • Checks that go is available.
  • Runs go build -o goto ..
  • Installs goto and a gt copy to ${GOTO_INSTALL_DIR:-$HOME/.local/bin}.
  • Prints persistent shell-integration next steps for your detected shell.
• install.ps1 for Windows:
  • Checks that go is available.
  • Runs go build -o goto.exe ..
  • Installs goto.exe and a gt.exe copy to $env:LOCALAPPDATA\Programs\goto by default.
  • Adds the install directory to the User PATH if needed and prints persistent PowerShell integration next steps.

Enable shell integration

This step is required for goto <name> or gt <name> to change your shell's current directory. The goto and gt binaries can print a path, but a subprocess cannot cd the parent shell. The shell integration defines wrapper functions that call goto path <name> and change directory in your current shell. It also enables tab completion of marked names for both goto and gt.

The easiest persistent, one-time setup is:

goto install bash
goto install zsh
goto install fish

For PowerShell:

goto install powershell

goto install <shell> writes a managed block to your shell startup file and is safe to run more than once. It uses these files:

• bash: ~/.bashrc
• zsh: ~/.zshrc
• fish: ~/.config/fish/config.fish
• PowerShell: your PowerShell $PROFILE

The managed block is delimited by:

# >>> goto shell integration >>>
# <<< goto shell integration <<<

Open a new shell, or source/reload the startup file, after running goto install <shell>. The goto/gt wrappers and tab completion are then active automatically.

Manual setup with goto init <shell> still works if you prefer to edit your startup file yourself:

bash

Add to ~/.bashrc:

eval "$(goto init bash)"

zsh

Add to ~/.zshrc:

eval "$(goto init zsh)"

fish

Add to ~/.config/fish/config.fish:

goto init fish | source

PowerShell

Add to $PROFILE:

goto init powershell | Out-String | Invoke-Expression

Restart your shell, or source/reload the startup file, after updating it.

Usage

Use either goto or gt with the same commands: add, remove/rm, list/ls, path, scan, init, install, version, help, and <name> for jumping after shell integration.

Mark the current directory:

goto add tt-azure

or with the short alias:

gt add tt-azure

Mark a specific path:

goto add docs C:\github\thomas-temby\goto

List marks:

goto list

or:

goto ls
gt list

Jump to a mark after shell integration is enabled:

goto tt-azure
gt tt-azure

Print the resolved path for a mark:

goto path tt-azure

Scan for git repositories and mark them automatically:

goto scan C:\github

This recursively finds git repositories under C:\github and creates marks using each repository folder name. If two repositories share a folder name, goto disambiguates the mark name with a parent-directory prefix. After scanning, jump to a scanned repository by name:

goto goto
gt goto

Preview scan results without writing marks:

goto scan . --dry-run
goto scan . -n

Limit how deep the scan searches:

goto scan C:\github --depth 3
goto scan C:\github -d 3

If you omit the root, goto scan scans from the current directory.

Remove a mark:

goto remove tt-azure

or:

goto rm tt-azure

Other commands:

goto version
goto help
gt version
gt help

Tab completion

After shell integration is enabled, press TAB to list or complete marked names:

goto <TAB>
gt <TAB>
goto tt<TAB>
gt tt<TAB>

Completion works in bash, zsh, fish, and PowerShell. It is powered by a hidden goto __complete command; users normally do not run that command directly.

Command reference

Command	Description
goto add <name> [path]	Mark the current directory or a specific path.
goto remove <name> / goto rm <name>	Remove a mark.
goto list / goto ls	List marks.
goto path <name>	Print the path for a mark.
goto scan [root] [--depth N] [--dry-run]	Find git repositories under root and mark them automatically.
goto scan [root] [-d N] [-n]	Short flag form for --depth and --dry-run.
goto init <shell>	Print shell integration for manual setup.
goto install <shell>	Persist shell integration and completion in your startup file.
goto version	Print the version.
goto help	Print help.
goto <name> / gt <name>	Jump to a mark after shell integration is enabled.

Configuration

Marks are stored in your home directory at:

~/.goto/marks.json

The file contains a JSON array of mark objects:

[
  {
    "name": "tt-azure",
    "path": "C:\\github\\thomas-temby\\azure-powershell"
  }
]

Each object has:

• name: the custom mark name.
• path: the directory path to jump to.

Uninstall

1. Remove the goto/gt or goto.exe/gt.exe binaries from the directory where they were installed.

2. Remove shell integration from your shell startup file. If you used goto install <shell>, delete the managed block between # >>> goto shell integration >>> and # <<< goto shell integration <<<.

3. Optionally delete stored marks:

   rm -rf ~/.goto

   On Windows PowerShell:

   Remove-Item -Recurse -Force "$HOME\.goto"