How-Tos¶

Add a config file to ToolTamer¶

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

Open tt --admin → "Move local file to ToolTamer"
Select the target config (your host or common)
Enter the path to the file
ToolTamer copies it to the 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
```

Move a config file between configs¶

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

Open tt --admin → "Move files between configs in ToolTamer"
Select source config, then target config
Select the file to move

ToolTamer moves the file 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:

Open tt --admin → "View differences of installed tools"
Or manually: remove the line from your host's file and add it to common/to_install.brew

Fix duplicate packages¶

When including multiple configs, the same package may be listed in several places. This is harmless but messy:

Open tt --admin → "Fix duplicate packages"
ToolTamer removes packages from your host config that are already covered by included configs

View what's different¶

File differences¶

tt --admin → "View differences of files"

Shows a diff for each configured file where the ToolTamer version and the system version differ. For each difference, you choose:

Take system version — update ToolTamer with the local change
Restore ToolTamer version — overwrite the local file
Skip — do nothing

Package differences¶

tt --admin → "View differences of installed tools"

Shows packages that are missing (in config but not installed) or excess (installed but not in config). Use TAB to multi-select, then:

Key	Action
F1	Install selected missing packages
F3	Remove selected excess packages from system
F5	Add selected excess packages to ToolTamer config
F7	Remove selected missing packages from ToolTamer config

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 System" 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
```