External template

Some projects will not let you add a thinslice.new-state file.

Fortunately thinslice lets you can keep your template script somewhere else on disk and point thinslice at it via the user level config file.

How it works

Normally thinslice looks for thinslice.new-state in the worktree itself (see Template for the search order). When that fails — or when you want to ignore what the repo provides — thinslice consults ~/.config/thinslice/config.toml for a mapping keyed by the project root path.

# ~/.config/thinslice/config.toml

[["thinslice.new-state"]]
project = "/Users/you/src/work-repo"
path = "/Users/you/src/my-work-repo-setup/thinslice.new-state"
mode = "fallback"

[["thinslice.new-state"]]
project = "/Users/you/src/other-repo"
path = "/Users/you/src/other-repo-personal/thinslice.new-state"
mode = "override"

Quoted because TOML would otherwise read the dot as a key separator. Each entry is matched by the absolute path of the project root aka the directory you ran slice setup in, the directory that contains +clone+/, main/, local/, etc... See (setup)[./setup.md]. Symlinks are fully resolved before comparison; trailing slashes are ignored.

Fields

Field	Description
project	Absolute path to the project root that this entry applies to.
path	Absolute path to the thinslice.new-state script to use. The file must be executable.
mode	"fallback" or "override". Default is "fallback".

fallback vs override

mode = "fallback" means "use the external script only if the repo doesn't have one." thinslice does its normal repository search first; if it finds a thinslice.new-state in the worktree, that wins. The external script is consulted only when the in-tree search comes up empty.

This is the safe default. If your colleague later adds an official template to the repo, your local setup switches over to it but prints a warning message.

mode = "override" means "always use the external script, even if the repo has its own." Use this when the in-tree template exists but doesn't suit you. For example, the repo's template assumes Docker and you're running everything natively, or it hardcodes paths that don't exist on your machine (grrrr). Override lets you ignore the repo's version without touching the repo.

See also: Template → Discovery for the exact search order.

Example

A clean way to organize this is to keep a small sibling directory next to the locked repo:

~/src/
  work-repo/                          
    +clone+/                          # the locked down repo
    main/
    local/
    ...
~/.local/config/                        # your personal dotfiles repo
    .git/
    work-repo-customization/            
      thinslice.new-state               # executable 

The external script is invoked exactly the same way an in-tree script would be — same input environment variables (SLICE_STATE_DIR, SLICE_CODE_DIR, SLICE_PROJECT_DIR, BRANCH), same TOML-on-stdout contract. From the script's point of view, nothing is different.

How do I know which thinslice.new-state file will be used?

Run slice inspect. It prints the resolved path and where it came from:

$ slice inspect

Using thinslice.new-state from your global config:

    /Users/you/src/my-work-repo-setup/thinslice.new-state

It matched this entry in ~/.config/thinslice/config.toml:

    [["thinslice.new-state"]]
    project = "/Users/you/src/work-repo"
    mode    = "fallback"

The repo has no thinslice.new-state of its own, so the fallback applied.

When something doesn't go the way you expected — you added an override and it didn't take, or thinslice can't find any template at all — slice inspect is the first place to look. It writes the resolution as a small story so you can see which branch was taken and why:

-- I COULDN'T FIND A THINSLICE.NEW-STATE -----------------------------

I looked for a thinslice.new-state to use for this worktree:

    /Users/you/src/work-repo/local/magic-search

First, I checked your global config at /Users/you/.config/thinslice/config.toml
for an override entry matching this project. I didn't find one.

Next, I looked inside the worktree, in these three places:

    ./thinslice.new-state
    ./src/thinslice.new-state
    ./config/thinslice.new-state

None of them exist.

Finally, I went back to /Users/you/.config/thinslice/config.toml and
checked for a fallback entry matching this project. The closest entry
I found was:

    [["thinslice.new-state"]]
    project = "/Users/you/src/work-repo/"
                                       ^
    path    = "/Users/you/src/my-work-repo-setup/thinslice.new-state"
    mode    = "fallback"

The trailing slash on `project` keeps it from matching. Project paths
are compared without trailing slashes. Try:

    project = "/Users/you/src/work-repo"

Hint: `slice inspect --project` prints the exact path I compare against.

The pattern is the same for other failure modes — an entry whose path points at a missing file, an override that matched but isn't executable, two entries that both claim the same project. In each case slice inspect names what it tried, what it found, and the smallest concrete edit that would fix it.