--- name: tower-cli description: Opens Git repositories in Tower (the Git client for Mac) at a specific view using the `gittower` command line tool — History, a single commit, Blame, the Working Copy, Stashes, Branches Review, Pull Requests, repository settings, or the clone dialog — and reads or sets Tower's stacked-branch metadata. Use when the user wants to see, review, or inspect something in Tower ("show me this in Tower", "open the diff in Tower", "blame this file in Tower", "which branches are stale?"), and when you have finished making changes and the user should review them before committing. --- # Tower Command Line Tool (`gittower`) `gittower` is a launcher for Tower, not a Git client. Every command covered here except `branch` opens Tower at a particular view and exits; it never commits, pushes, checks out, or modifies files. Use `git` for Git operations and `gittower` to show the user the result in Tower. Requires Tower 18 or later for Mac. Check with `gittower --version`, which should match Tower's own version. If the command is missing or older, ask the user to click **Install** or **Update** in Tower → Settings → Integration → Tower Command Line Tool. ## When to use it - **After you change files.** When you finish a task that modified the working tree, offer to open the changes in Tower for review, or run `gittower working-copy` if the user has asked you to do that. Reviewing a diff in Tower beats reading one in the chat. - **When the user wants to look at something:** a file's history, who changed a line, a commit you mentioned, branches that need cleaning up, open pull requests. - **Not for Git operations.** To commit, push, merge, or create branches, use `git`. Opening Tower brings it to the front, so run a view command once when it's useful, not repeatedly in the background. ## Commands | Command | Opens | |---|---| | `gittower .` or `gittower ` | The repository (paths inside a working tree resolve to its root; a file path opens its repository) | | `gittower history []` | History: all commits, or scoped to a ref, a file, or `:` | | `gittower commit ` | History with that commit selected (any revision Git resolves: hash, tag, `HEAD~2`) | | `gittower blame ` / `blame :` | Blame for the file, now or as of a revision (a file is required) | | `gittower working-copy` (alias `status`) | The Working Copy view: uncommitted changes | | `gittower stashes` | The Stashes view | | `gittower branches-review [options]` | Branches Review (options below) | | `gittower pull-requests` (alias `prs`) | The Pull Requests view | | `gittower settings` | The repository's settings | | `gittower clone ` | Tower's clone dialog with the URL filled in (https, ssh, or `user@host:path`); Tower picks the destination | `history` scopes which commits are listed; `commit` selects one. Use `commit` when you want to point the user at a specific commit. ### Branches Review options - `--filter `: one of `none`, `mergeable`, `fully-merged`, `conflicts`, `active`, `stale`, `tracking-error`, `has-pr`, `no-pr` - `--branch `: preselect a branch's row - `--base `: compare against this branch - `--search `: prefill the search field - `--sort name|last-updated` and `--desc` Example: `gittower branches-review --filter fully-merged` shows branches that are safe to delete. ### Options for every view command - `-C `: run as if started in that directory (defaults to the current one). Prefer this over `cd`. - `-n` / `--new-window`, `--new-tab`: where Tower opens the repository. `open` and `clone` take a path or URL instead of `-C`. One repository per invocation; use a shell loop for several. ## Naming things unambiguously - Git's `:` notation works for `history` and `blame`: `gittower blame v1.0:src/Parser.swift`. - If a name is both a ref and a file, `gittower` refuses to guess. Use `./` or `-- ` for the file, and `refs/heads/` or ` --` for the branch. - A file that starts with a dash: `gittower history -- -notes`. - A directory whose name matches a command needs the explicit form: `gittower open history`. - `gittower open ` on a folder that isn't a repository offers to create one, so don't point it at arbitrary folders. ## Stacked branch metadata `gittower branch` is the only command covered here that doesn't open Tower. It reads and writes Tower's branch stacking information, which lives in the repository's Git config. Reading is always safe: ``` gittower branch parent [] # prints the parent (exit 0), or nothing if there is none (exit 1) gittower branch stacked [] # prints true (exit 0) or false (exit 1) ``` `` defaults to the checked-out branch. Writing changes how Tower treats the branch, so **ask the user first**: ``` gittower branch parent --set # record the parent (does not stack it) gittower branch parent --clear # remove the parent and the stacked flag gittower branch stacked --set # mark as stacked on its parent (needs a parent) gittower branch stacked --clear # clear the stacked flag, keep the parent ``` If Tower is running, it picks up the change the next time it reloads branches, so don't tell the user it's already visible there. ## Exit codes `gittower` uses standard Unix exit codes: - `0`: the request was sent to Tower, or the value was read or written (`true` or a parent name was printed). - `1`: the answer is no — a result, not a failure, and stderr is empty. For example, `branch stacked` printed `false`, or `branch parent` printed nothing because the branch has no parent. - Anything else: nothing happened, and the reason is on stderr (for example, the current directory isn't inside a repository). Report that message to the user rather than retrying blindly. For view commands, `0` means the request was sent to Tower, not that the view opened. If Tower can't open windows (for example, because the trial has expired), it drops the request and the exit code is still `0`. If the user says nothing appeared, check Tower itself. For the full reference of any command, run `gittower help ` (or `gittower help branch parent`).