hams store

Manage the store repo — the git repository that holds your Hamsfiles and hams.config.yaml. The store is hams’s source of truth: it’s what apply --from-repo pulls from and what your everyday changes get pushed to.

Usage

hams store <subcommand> [flags]

Subcommands

hams store init

Spin up a new store in the current directory. Creates hams.config.yaml, a profile directory, and a .gitignore (which auto-ignores .state/ and *.local.*).

mkdir my-hams-store && cd my-hams-store
hams store init
# Prompts for profile tag and machine ID

Turn it into a git repo, push it to GitHub, and you’re ready to share across machines.

hams store clone <repo>

Pull someone else’s store (or your own on another machine) down to this box and point hams at it.

# From GitHub
hams store clone zthxxx/hams-store
 
# Now just apply
hams apply

Essentially a git clone followed by hams config set store_path, in one step.

hams store status

Show the store’s current state: uncommitted changes, ahead/behind remote, which profile is active.

hams store status

Sample output:

Store:       /Users/you/Projects/hams-store
Branch:      main (up to date with origin/main)
Profile:     macOS
Machine:     MacbookProM3

Modified:
  macOS/Homebrew.hams.yaml
  macOS/pnpm.hams.yaml

Untracked:
  (none)

hams store push

Stage, commit, and push Hamsfile changes in a single step. Uses a generic default commit message or accepts your own via -m.

# The full shortcut — uses the default "hams: update store" message
hams store push
 
# Use your own message (recommended for audit-friendly history)
hams store push -m "Add ripgrep and htop"

A clean working tree short-circuits to a friendly “nothing to commit” message and exits zero — running hams store push right after hams refresh (which only mutates gitignored .state/ files) doesn’t fail.

store push won’t push .state/ or *.local.* files — those are already gitignored.

hams store pull

Grab the latest Hamsfiles from the remote. If there are changes, run hams apply to put them into effect.

hams store pull
hams apply   # bring this machine in line with the updated Hamsfiles

Store layout

hams-store/
├── hams.config.yaml              # Project config (committed)
├── hams.config.local.yaml        # Local overrides (not committed)
├── .state/<machine-id>/          # Per-machine state (gitignored)
└── macOS/                        # Profile directory. You can have several: macOS/, openwrt/, work-linux/
    ├── Homebrew.hams.yaml        # Main Hamsfile (committed)
    └── Homebrew.hams.local.yaml  # Machine-specific (not committed)