Project settings files

A repository's Mergepond settings live in two TOML files at the root of its main worktree. .mergepond.toml is committed and shared with everyone who clones the repository. .mergepond.local.toml is yours alone, and Mergepond keeps it out of Git. Both Mergepond and pond read them, so the app and a coding agent agree on where worktrees go, how they are set up, and who commits.

Where to find it

• Worktrees tab › gear edits the worktree and agent keys, with a Share with the team checkbox that chooses the file.
• The files themselves, in any editor: .mergepond.toml and .mergepond.local.toml beside .git.
• pond policy reads and writes the isolation key from a terminal.

The two files

A key in your local file wins over the same key in the team file. A key in neither comes from the old mergepond.* Git config, if the repository still has it, and otherwise from Mergepond's defaults.

Both files sit at the root of the main worktree, not of each worktree, so every worktree of a repository reads the same settings.

Every key

workspace = "Acme"                     # a Mergepond workspace, by name
identity = "Work"                      # an identity profile, by name

[worktrees]
location = "../<repo>.worktrees/<branch>"

[setup]
copy = [".env", ".env.local"]          # files that aren't in Git, copied from the main folder
link = ["node_modules"]                # folders shared with the main folder through a symlink
run = ["pnpm install"]                 # commands run in the new folder, in order

[agents]
isolation = "always"                   # always, when-asked or ask
branch = "agent/<agent>/<task>"        # <agent> becomes claude-code or codex

Placeholders can be written <branch> or {branch}. A key the files don't know is an error: Mergepond and pond say which key, in which file, rather than ignoring it.

Identity

The committed file may only name a profile, because a name and email in it would commit everyone who clones the repository as the same person. If .mergepond.toml has [identity] with a name and email, Mergepond refuses to read it and says: ".mergepond.toml spells out a name and email under identity. It's committed, so it may only name a profile (identity = "Work"); put the name and email in .mergepond.local.toml instead."

In your local file either form works:

identity = "Work"

[identity]
name = "Ada Lovelace"
email = "ada@example.com"
signing-key = "ABCD1234"               # optional
signing-format = "ssh"                 # optional: openpgp or ssh
ssh-key = "~/.ssh/id_ed25519_work"     # optional

A named profile is matched against your identities by label, ignoring case, then by id. An identity spelled out inline shows in the commit box under the label .mergepond.local.toml.

When Mergepond works out who a repository should commit as, it takes the first of these that is set:

1. identity in .mergepond.local.toml.
2. The repository's own pick in the app, "Always label" in Repository settings.
3. identity in .mergepond.toml.
4. The identity of the workspace the repository belongs to.

So a teammate's .mergepond.toml naming "Work" is used unless you have pinned the repository to something else or your local file says otherwise. If the repository's Git config disagrees with the identity a file names, the commit box warns that the repository's settings file commits as someone else, with a Use label button that writes the file's identity into the repository's Git config, as described in Git identities.

Share with the team

Worktree settings has a Share with the team checkbox under its fields. The hint under it says where the sheet will save:

• Unticked: "Saved in .mergepond.local.toml, which only you have. Git ignores it." Save shows the toast "Saved the worktree settings."
• Ticked: "Saved in .mergepond.toml at the top of the repo. Commit it, and everyone gets these settings." Save shows "Saved to .mergepond.toml. Commit it to share it."

The sheet is ticked when the team file already holds these settings. When you save with it ticked, the six worktree and agent keys are removed from your local file, so the team's settings take effect for you too. The sheet writes only the keys that differ from what the layers underneath already give, and it edits the file in place, so comments and other keys you wrote by hand stay.

The choice a coding agent saves through worktree_policy or pond policy always goes to the local file. Tick Share with the team in the sheet to move it to the committed one.

Moving from Git config

Before 1.0.6 Mergepond kept the folder pattern and the setup recipe in the repository's Git config, as mergepond.worktreePattern, mergepond.recipeCopy, mergepond.recipeLink and mergepond.recipeRun. Those keys are still read, below both files, so nothing changes until you save. The first time you save Worktree settings in a repository that has them, Mergepond writes the values into a file and unsets the four keys. pond reads the keys the same way but never writes them.

The identity keys Mergepond writes into .git/config (user.name, user.email and the rest) are unchanged: they are what Git itself reads, and the files only decide which identity Mergepond expects there.

Free and Pro

Both files, every key, and the Worktree settings sheet work on Mergepond Free. Repositories over SSH read and write the same files on the host, with Pro.

Related guides

• Worktrees that set themselves up
• Let your coding agent make its own worktrees
• Workspaces, windows and Git identities