How-Tos¶

These describe the TUI, which is what tt opens. Every screen lists its keys in the footer, so you never have to remember them.

Add a config file to ToolTamer¶

You have a config file (e.g. ~/.config/starship.toml) that you want to manage with ToolTamer.

tt → File Manager (d)
Press n to add a file. With fzf installed you get a fuzzy picker over your home directory; otherwise a directory browser opens.
Choose the target config (your host, common, or a shared one)

ToolTamer copies the file into that config's files/ directory and adds the mapping to files.conf.

Or manually:

Copy the file:

cp ~/.config/starship.toml ~/.config/toolTamer/configs/common/files/starship.toml

Add to files.conf:
```
starship.toml;.config/starship.toml
```

Or from the shell, without opening the TUI:

tt --add ~/.config/starship.toml

Track a git repository instead of copying it¶

You have a directory under ~ that is itself a git repository (e.g. ~/.config/nvim) and want ToolTamer to keep it up to date via git clone/git pull instead of mirroring its files — and its .git directory — into the ToolTamer store.

Do this first: update ToolTamer on every machine that shares this config. The config store travels between your machines on its own, and a machine still running an older tt does not recognise a .ttgit marker. It treats the marker directory as a plain tracked directory and mirrors it over the repository on that machine — copying the marker in and deleting everything else, .git and uncommitted work included. Nothing on the new side can prevent that, so bring every host up to date before you create your first repo entry.

Open tt (or tt --admin) → File Manager, then press n and pick the repository's root directory. With fzf installed you get a fuzzy picker over everything under ~ (faster when fd is also installed); without fzf, a directory-tree browser.
ToolTamer detects that the path is the root of a git repository (with an origin remote) and asks whether to track as repo or copy contents. Picking a plain file, or a directory that is not itself a repo root, skips this and adds it normally.
Choose Track as repo. ToolTamer records the detected origin URL and current branch in a .ttgit marker and adds the usual files.conf entry — the store then holds only that marker, never the repository's contents.

From then on, a (apply TT → system) clones the repository where it's missing and fast-forwards it where it's behind; u (save) only ever refreshes the marker's url/branch from the system, never its content. See Git repositories for the full sync behavior and its limits.

Convert an already-tracked directory into a repo entry¶

You already copy a directory into ToolTamer the normal way, and only later turned it into (or noticed it already is) a git repository on your system.

The same warning applies here as above: every machine sharing this config needs the current tt before you convert an entry, or an old tt on another host will mirror the marker directory over your repository and delete its contents.

Select the entry in the file manager and press g. This is only offered when the tracked entry is a directory, is not already a repo entry, and ~/<target> on your system is currently the root of a git repository.
A confirmation dialog shows the detected origin URL and branch, and how many stored files will be removed from the ToolTamer store once the entry becomes a marker-only repo entry. Your system copy is never touched by this step.
Confirm with y. ToolTamer deletes the entry's stored content and writes a .ttgit marker in its place; files.conf itself does not change.

If a tracked directory's system side is detected as a git repository root but hasn't been converted, the detail pane says so and reminds you that g will do it.

Move a config file between configs¶

You have a file in your host config that should be shared via common:

tt → File Manager (d)
Select the file, press m
Pick the target config

ToolTamer moves the stored copy and updates both files.conf entries.

Move a package between configs¶

A package is listed in your host's to_install.brew but should be in common:

tt → Package Manager (p)
Select the package, press m (or c to copy instead of move)
Pick the target config

To move several at once, mark them with Space first — m then applies to the whole selection and asks once for the destination.

Install or remove packages¶

In the Package Manager (p), the status column tells you where each package stands:

Status	Meaning
`OK`	in a config and installed
`!!`	in a config but missing on this machine
`++`	installed but in no config
`D`	required by another installed package

Key	Action
`i`	install the selected package
`x`	uninstall it from the system
`a`	add it to a config
`r`	remove it from its config (leaves it installed)
`u`	uninstall and remove from the config
`d`	hide/show dependency-only packages
`Space`	mark a row — `x`, `m`, `r` and `u` then act on all marked rows
`/`	filter (also accepts a status: `!!`, `OK`, `++`)

Uninstalling is checked against the real dependency graph first: if another installed package still needs it, the removal is refused and tells you what depends on it, rather than failing halfway through.

For bulk actions you get a preview listing what will be processed and what is skipped (with the reason) before anything happens.

View what's different¶

File differences¶

tt → File Manager (d). Each tracked file shows its status, and selecting one shows a diff against what's actually on disk:

Status	Meaning
`OK`	identical
`!!`	differs
`--`	missing on the system
`<<`	shadowed by another config
`==`	duplicate within the same config

Then choose per file:

a — apply the ToolTamer version to the system (overwrites the local file)
u — save the local change into ToolTamer. For inherited files you are asked whether it should go into the shared config (affecting all hosts) or become a host-local override.
r — stop managing the file (leaves it on the system)

Directories are supported and diffed recursively; before a sync that would delete files on the destination, you get an explicit confirmation listing them.

Package differences¶

tt → Package Manager (p) — see the table above. Filter with / to see only one category, e.g. !! for everything missing.

Manage Homebrew taps¶

tt → Tap Manager (t, macOS only):

Key	Action
`a`	add a tap to a config
`r`	remove a tap from a config
`m`	move a tap to another config
`t` / `u`	tap / untap on this machine
`s`	sync all configured taps

Note that a package listed under its fully qualified name (forketyfork/tap/clawtunes) does not need a tap entry — brew adds the tap itself. See Configuration.

Clean up the config¶

Two one-off audit tools, both dry-run by default:

tt --fix-taps        # rewrite tap packages to their fully qualified names
tt --cleanup-deps    # drop packages only listed because something depends on them

Add --apply to actually change anything; you get a preview and a confirmation prompt first. tt --cleanup-deps --keep <package> protects individual packages from removal.

Use ToolTamer without interaction¶

For scripting or cron jobs:

tt --syncSys            # Full sync (packages + files + local_install.sh)
tt --syncFilesOnly      # Only sync files
tt --updateToolTamer    # Snapshot packages
tt --updateToolTamerFiles  # Snapshot packages + files

Set up a shared config for multiple Macs¶

Create common_mac/ with shared macOS packages and configs
In each Mac's includes.conf, add:
```
common_mac
```
Put Mac-specific overrides (like different Homebrew taps) in the host directory

Create a config for a new machine¶

Install ToolTamer on the new machine
Run tt — provide your Git repo URL
ToolTamer creates a host directory based on the hostname
Use Snapshot (s) to capture the current state
Or: create a symlink to an existing host config if the setup should be identical:
```
cd ~/.config/toolTamer/configs
ln -s existingHost newHostname
```