Branches and merging

Set your conventions

A [branches] section in nool.toml sets each kind's name pattern and the branch it starts from. Placeholders: {slug}, {ticket}, {version}, {date} and {user}. Agents read the conventions at the start of every session.

[branches]
feature = { pattern = "feature/{ticket}-{slug}", base = "develop" }
hotfix  = { pattern = "hotfix/{version}", base = "main" }

Create and check branches

nool branch new creates a branch named by the convention from its base and switches to it. nool branch check validates a name, and nool branch conventions prints them. While the section is enforced, git switch -c, git checkout -b and git branch refuse names that fit no convention; enforce = false keeps them as guidance only.

nool branch new hotfix "token refresh" --version 7.16.1
nool branch check
nool branch conventions

Land a fleet on a branch

--into switches the repository to the target branch before the fleet starts, creating it from --base, the convention's base, or the default branch, and every task lands there.

nool code --fleet "add search" --into feature/DOC-142-search --base develop

Land a change on a side branch

`nool try promote --onto <branch>` seals the change as usual but puts its commit on a side branch, leaving your checkout alone; `nool status` lists it as awaiting a merge until `nool pull` sees the branch merged, including through GitHub's squash and rebase buttons. `nool push <remote> --branch <branch>` pushes that branch with its mirror pointer. In `nool code`, `[code] land_target = "branch"` does this for every session and `[code.pr]` opens the pull request.

nool try promote <try-branch> --onto feature/DOC-142-search
nool push origin --branch feature/DOC-142-search

Leases across branches

A lease records the branch it was taken on. Two agents changing the same files on different branches no longer block each other: the second is granted with a warning that the changes will meet in a merge. On the same branch, overlap still conflicts.

Merge pull requests (Team)

Every Nool commit updates .nool/knot.bin, which GitHub's merge button cannot merge when both branches moved. nool pr merge merges the branch through Nool, recording both sides' history; the merge-queue workflow runs it when an approved pull request is labelled nool-merge. If your team uses GitHub's merge button on Nool side branches anyway, add the mirror-advance workflow from the GitHub Actions guide so Nool's mirror pointer follows `main`.

nool pr merge feature/DOC-142-search --into develop --push