ivar feature
The feature lifecycle on the command line — create, promote, demote, rebase, integrate, close and prune.
A feature is a name, a branch, and the set of repos that branch exists in.
It is the unit ivar uses to decide what an agent may write to and what gets
delivered together.
Create a feature
ivar feature create billing-currencyThe name is one path segment, unique in the hall, and becomes the branch name.
When the branch has to be spelled differently than the feature — feat/login,
say — pass --branch:
ivar feature create login --branch feat/login--base sets the branch new promotions start from, per repo. Left off, each
repo starts from its own default branch.
A new feature owns no repos yet
create records the feature and nothing else. Repos join it one at a time
through promote, which is what makes scope an explicit decision rather than
a guess made up front.
Promote the repos it touches
ivar feature promote billing-currency api
ivar feature promote billing-currency webPromotion cuts the feature's branch in that repo and materialises its worktree.
A branch that already exists is adopted as it is; one that does not is created
off the repo's effective base. --base overrides that start point for a single
repo.
Everything you did not promote stays on its default branch — and, inside a session, stays read-only. That is the mechanism described in the guard.
When scope moves
Scope is rarely right the first time. It is normal to find, halfway through, that the change reaches one repo further:
Promote the repo you now need. The worktree appears and the guard lifts for it.
ivar feature promote billing-currency sharedOr take one back out. demote removes the repo from the feature and leaves
its worktree on disk, so nothing you already wrote is lost.
ivar feature demote billing-currency infraInspect
ivar feature list # every feature and how far it got
ivar feature status billing-currency # one feature, repo by repostatus --recursive reports a feature's whole subtree.
Keep up with the base
ivar feature rebase billing-currencyEvery promoted worktree is rebased onto its effective base. A dirty worktree is
skipped rather than stashed, and a conflict is aborted and reported — ivar
will not leave you inside a half-finished rebase.
Subfeatures
A feature can be created under another one, deriving its base from the parent's branch instead of a repo default:
ivar feature create billing-currency-ui --parent billing-currencyivar feature integrate lands a child into its immediate parent, leaves first,
one promoted repo at a time — durable and resumable. The integration policy
(--via pr or local, --strategy squash, merge or rebase) is persisted
when the feature is created; after the first receipt it is frozen.
ivar feature reparent moves a still-pristine child under a different parent.
It is refused the moment anything real exists under the feature — a promotion, a
plan, a session, a receipt or a descendant.
Finish up
ivar feature close billing-currency # stop executors, record the outcome
ivar feature delete billing-currency # worktrees, .ivar/ directory and plans
ivar feature prune # drop features already merged into their default branchesclose is idempotent — closing a closed feature does nothing. delete refuses
if anything under the feature directory cannot be removed, and keeps the feature
record so you can retry.