# SCM Breeze: Numbered File Shortcuts and a Repository Index for Git in the Shell

> SCM Breeze is a set of bash and zsh shell scripts that replace long file paths in git commands with short numbered references. It also adds a repository index with tab completion for switching between projects. The tool requires Ruby for full functionality.

**scmbreeze/scm_breeze** — Adds numbered shortcuts to the output git status, and much more

- Repository: https://github.com/scmbreeze/scm_breeze
- Website: https://madebynathan.com/2011/10/19/git-shortcuts-like-youve-never-seen-before/
- Stars: 2,912 · Forks: 207
- Language: Shell
- License: MIT
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/scmbreeze-scm-breeze

## What SCM Breeze Does and Who It Is For

SCM Breeze intercepts the output of `git status` and assigns each changed file a numbered environment variable. The default prefix is `e`, so the first changed file becomes `$e1`, the second `$e2`, and so on. Any git command or shell command can then reference files by number instead of by path.

The tool is for developers who use git heavily from the terminal and want to avoid typing or copy-pasting full file paths. It does not add graphical elements or change how git stores data. It only modifies what appears in the shell and what shortcuts are available there.

## How the Numbered Shortcut System Works

After running `git status` through SCM Breeze, each path in the output is stored in a numbered variable. The variable prefix is configurable in `~/.git.scmbrc`. With the default prefix, a git add command that would normally require the full path can be written as:

```bash
$ ga 2 3 11
```

The `ga` alias maps to the `git_add_shortcuts` function, which expands bare integers and ranges into the corresponding environment variables. To add a range of files:

```bash
$ ga 1-10
```

The same expansion works for diff, reset, and checkout:

```bash
$ gd 3
$ grs 4
$ gco 5
```

For system commands that are not aliased, the `exec_scmb_expand_args` function (default alias `ge`) performs the expansion:

```bash
$ ge echo 1-3
```

This expands to `echo $e1 $e2 $e3` and prints the corresponding file paths. The mechanism stores paths in shell environment variables, which means the shortcuts are only valid until the next time status is run and the variables are reassigned.

## Installing SCM Breeze and Verifying the Setup

Installation clones the repository to `~/.scm_breeze` and runs the provided install script:

```bash
git clone https://github.com/scmbreeze/scm_breeze.git ~/.scm_breeze
~/.scm_breeze/install.sh
source ~/.bashrc   # or source "${ZDOTDIR:-$HOME}/.zshrc"
```

The install script creates default config files and adds one line to `.bashrc` or `.zshrc` that sources SCM Breeze at shell startup:

```bash
[ -s "$HOME/.scm_breeze/scm_breeze.sh" ] && source "$HOME/.scm_breeze/scm_breeze.sh"
```

The README notes that Ruby is required for some commands to work and also improves performance. The exact commands that need Ruby are not listed at the top level; the note points to ruby-lang.org for installation guidance.

Before installing to the host shell, a Docker sandbox is available for testing. Build and run it from the repository root:

```bash
docker build -t scm_breeze-sandbox docker/
docker run --rm -it -v "$PWD:/workspace" scm_breeze-sandbox
```

Inside the container, `/workspace` is a bind-mounted copy of the repository, and `~/sandbox-repo` is a throwaway git repository pre-populated with staged, unstaged, and untracked changes. The test suite runs with `cd /workspace && ./run_tests.sh`.

## The Repository Index for Fast Project Switching

Beyond file shortcuts, SCM Breeze includes a repository index. Set `GIT_REPO_DIR` in `~/.git.scmbrc` to your projects root, then build the index:

```bash
$ c --rebuild
```

The default alias for the `git_index` command is `c`. After building, you can switch to any indexed project by typing a partial name with tab completion. The index also supports running a command across all repositories, which the README notes is useful for updating many remote URLs at once, and it can be triggered on a schedule via cron to keep all repositories updated.

This feature is similar in purpose to autojump but is specific to git repositories and does not require a learning phase. It can tab-complete into subdirectories of indexed projects, so a project organized into subfolders does not need a flat top-level layout to be accessible quickly.

## Keyboard Bindings and Alias Management

SCM Breeze provides two default key bindings. `CTRL+x c` calls `git_add_and_commit`, which adds any specified files and then commits staged changes. `CTRL+x SPACE` calls `git_commit_all`, which commits everything. Both use a `git_commit_prompt` function that provides a simple inline prompt.

The repository ships with a large set of aliases. Running `list_aliases` in the shell shows all of them with their corresponding commands. Filtering is supported: `list_aliases git log` narrows the output. The `git_aliases` command shows only git-specific aliases.

Configuration follows two paths. The first is to use the aliases SCM Breeze provides directly, adjusting them through `~/.git.scmbrc` and `~/.scmbrc`. The second is to ignore the provided aliases and define your own in your shell config, using the underlying functions directly.

## Real Limitations: Platform Support and Alias Conflicts

SCM Breeze works only on bash and zsh. The README does not describe Windows support, and there is no PowerShell or cmd.exe implementation. Engineers on Windows who are not using WSL cannot use this tool.

The alias system is the main source of friction. SCM Breeze adds a large number of short aliases to the shell. If any of these conflict with aliases already in `.bashrc` or `.zshrc`, the behavior of those shortcuts changes silently. The Docker sandbox exists precisely to catch such conflicts before they affect the host environment.

The numbered variable approach has a specific constraint: the variables are only valid until the next status call. If you run `git status`, note that file 3 is the one you want, and then run another git command that triggers a status refresh internally, the mapping may have changed by the time you use `$e3`. This is a natural consequence of storing state in environment variables.

Ruby is listed as a requirement for full functionality, but the README does not specify which features degrade without it.

## Alternatives and What Sets SCM Breeze Apart

The README itself lists autojump as an alternative to the repository index feature. Autojump is a shell navigation tool that learns from your cd history and suggests directories by partial name. SCM Breeze's `git_index` does not learn from usage; instead it scans a configured root directory and indexes all git repositories found there. This makes it predictable but also means it only knows about repositories under that one configured root.

For the file shortcut feature, the closest alternative approach is git's own interactive staging with `git add -p` or a terminal UI like lazygit. Lazygit is a terminal application written in Go that provides a full-screen interface for git operations including staging individual hunks. SCM Breeze stays in the shell prompt rather than opening a separate application, which suits workflows where leaving the current terminal context is disruptive.

## Maintenance and Version History

The last push to the repository was on 2026-07-23. The repository is not archived. The package.json at the repository root lists version 1.1.0 and describes the package as a CSpell plugin for extracting words from lockfiles. This file appears to be tooling for the development workflow rather than a version number for SCM Breeze itself, since SCM Breeze is a shell script package, not a Node.js package.

The repository has no GitHub releases. There is no changelog or release notes file visible at the top level. Updates are applied by pulling the main branch. The README includes an Updating section heading in its table of contents, though the README does not document what updating entails.

The license is MIT, located in the root LICENSE file.

## Conclusion

SCM Breeze suits engineers who spend most of their day in the terminal and find themselves typing long file paths into git commands. It requires Ruby, which adds a runtime dependency that some minimal environments will not have. The tool works only on bash and zsh, which rules it out for Windows users unless they are running WSL. Before installing, run the Docker sandbox to confirm the aliases do not conflict with your existing shell configuration, then check whether the scmbrc.example settings match your workflow.

## FAQ

### Does SCM Breeze work on Windows?

SCM Breeze is written for bash and zsh and the README does not describe Windows support. It can be used on Windows through WSL, which provides a bash environment.

### Why does SCM Breeze require Ruby?

The README states that Ruby is required for some SCM Breeze commands to work and that it improves performance, but does not list the specific commands affected. It points to ruby-lang.org for installation guidance.

### How do I see all the aliases SCM Breeze adds to my shell?

Run `list_aliases` in the shell to see all aliases with their corresponding commands. To filter, add a search string such as `list_aliases git log`. The `git_aliases` command shows only git-specific aliases.

## Sources

- [Issues](https://github.com/scmbreeze/scm_breeze/issues)
- [License: MIT](https://github.com/scmbreeze/scm_breeze/blob/main/LICENSE)
- [Project website](https://madebynathan.com/2011/10/19/git-shortcuts-like-youve-never-seen-before/)
- [README](https://github.com/scmbreeze/scm_breeze/blob/main/README.md)
- [scmbreeze/scm_breeze on GitHub](https://github.com/scmbreeze/scm_breeze)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/scmbreeze-scm-breeze