Docs / Going further

Repo settings

Tell Flotilla how to get each new worktree of a repo ready: what to run, what to copy in, and what the editor leaves out.

The two files

Each repo can have two settings files in a .flotilla folder at its top:

• .flotilla/settings.json is committed and shared with everyone who works on the repo.
• .flotilla/settings.local.json is yours alone. Flotilla writes a .flotilla/.gitignore that keeps it, and everything else in the folder, out of git.

Both files apply; neither replaces the other. Commands from both run, the shared file's first. Lists from both are combined.

Each file is read from the worktree at hand when it has one, else from the repo's main checkout. So a branch that changes settings.json uses its own version in its worktree, and a settings.local.json in the main checkout covers every worktree.

To start one, open Edit Project in Flotilla, unfold Ready worktrees, sleeping agents, repo settings, and click Create Settings File. Flotilla writes a starter settings.json in each of the project's repos that has none and opens it in the editor.

An example

{
        "$schema": "https://tinypenguin.com/flotilla/settings.schema.json",
        "worktree": {
          "setup": "npm install",
          "copy": [".env.local", "config/master.key"],
          "cleanup": "./scripts/cleanup-checkout.sh \"$FLOTILLA_CHECKOUT\""
        },
        "editor": { "exclude": ["node_modules", "/build"] }
      }

Every key is optional, and Flotilla ignores keys it does not know.

Keys

worktree.setup

A command to run in each new worktree before an agent works in it: installing dependencies, generating a project, preparing a database.

"setup": "bundle install && bin/rails db:prepare"

If the shared file's setup fails, or you choose not to run it, the local file's setup does not run either. A failure shows in Flotilla's status line, and the agent starts anyway.

worktree.copy

Files and folders to copy from the repo's main checkout into each new worktree. Use it for what git does not track but the code needs, such as secrets and local config.

"copy": [".env.local", "config/master.key", "certs/*.pem"]

• Paths are relative to the top of the checkout. The last part may use *, ? and [...] wildcards; the folders before it are matched exactly.
• A folder is copied with everything in it. Files already in the worktree are never overwritten.
• On APFS the copies are clones, so even large folders copy quickly and take no extra space until they change.

worktree.cleanup

A command to run when a worktree or a session goes away, so whatever was made for it can go too: a simulator, a dev server's port, a database, a cache. Flotilla knows nothing of these; the command gets the variables below and decides what to do.

"cleanup": "./scripts/cleanup-checkout.sh \"$FLOTILLA_CHECKOUT\""

editor.exclude

Files and folders that Flotilla's editor leaves out of its file tree, Quick Open and Find in Files. They add to the list in Settings, under Editor.

"exclude": ["node_modules", "/build", "src/generated"]

• A bare name, like node_modules, matches a file or folder of that name at any depth.
• A path with a slash, like src/generated, or a leading /, like /build, matches from the top of the checkout only.

When commands run

Because ready worktrees are set up ahead of time, a slow setup does not hold up a new agent when Flotilla keeps worktrees ready for the project.

Commands run in bash, with the same environment as your agents: what your shell's startup files set, such as PATH from ~/.zshrc. A command can span several lines.

Variables

Setup and cleanup commands get these environment variables:

A cleanup script can branch on the event:

#!/bin/bash
      case "$FLOTILLA_EVENT" in
        checkout-removed) xcrun simctl delete "$FLOTILLA_CHECKOUT" 2>/dev/null ;;
        session-deleted)  rm -rf "/tmp/logs/$FLOTILLA_SESSION" ;;
      esac

Approving committed commands

Anyone who can commit to a repo can change its settings.json, so Flotilla does not run a command from it until you have seen it. The first time, it shows the command's exact text and asks whether to run it. Flotilla remembers your answer for that repo and that text, and asks again whenever the command changes. If you choose Don't Run, it is skipped and Flotilla asks again next time.

Commands in settings.local.json are your own and run without asking.

Editor help with $schema

Put this line first in either file, and editors such as VS Code and Zed check the file as you type, complete its keys and explain each one on hover:

"$schema": "https://tinypenguin.com/flotilla/settings.schema.json"

The starter file Flotilla writes already has it.