wdx worktree

Read a project’s worktrees, what is uncommitted and what a PR would show, land them and remove them.

All but land, rebase and remove only read, so they can run beside any git command: they take no lock on the repository. wdx agent create --worktree creates a worktree.

Command	What it does
`wdx worktree comments`	List the comments left on a worktree’s diffs
`wdx worktree diff`	Show what a worktree has committed, or what it has not
`wdx worktree land`	Land a worktree’s commits on its base, with no merge commit or through a PR
`wdx worktree list`	List every worktree git lists for a project, with its changes
`wdx worktree rebase`	Rebase a worktree onto its base, the default branch or a stacked plan’s plan below
`wdx worktree remove`	Remove a worktree that landed, with its branch

wdx worktree comments

List the comments left on a worktree’s diffs.

wdx worktree comments --name <worktree> [--project-id <id> | --project-name <name>] [flags]

Comments are written in TIDE, and sent to an agent together as a review. Each says whether it was sent.

Flags

Flag	Default	Description
`--name <name>`		name of the worktree, main for the clone
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

--name is required
at most one of --project-id or --project-name

Examples

# The comments on a worktree
wdx worktree comments --name auth-fix

# As JSON
wdx worktree comments --name auth-fix --project-name app --json

Output

The comments by file and line. With --json: {“comments”: […]}

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`invalid_path`	1	the path cannot be used
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

With --node, also: code_not_set_up, code_wrong, connection_lost, daemon_unavailable, hub_unreachable, hub_version_unsupported, node_key_mismatch, node_not_found, node_offline, node_version_unsupported, not_logged_in, remote_access_off, remote_not_for_agents, route_not_allowed, session_closed, session_required, too_many_streams.

wdx worktree diff

Show what a worktree has committed, or what it has not.

wdx worktree diff --name <worktree> [--uncommitted | --path <file>] [--project-id <id> | --project-name <name>] [flags]

By default, what the worktree has committed since it left its base, as a PR would show it: later commits on the base are not removals. With --uncommitted, everything not committed, untracked files too. With --path, the uncommitted changes of that file, with all of its lines.

Flags

Flag	Default	Description
`--name <name>`		name of the worktree, main for the clone
`--path <file>`		file to show the uncommitted changes of, relative to the worktree
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--uncommitted`		show everything not committed instead
`--node <name>`		run the command on the node of this name, another of your account, through a session

--name is required
at most one of --uncommitted or --path
at most one of --project-id or --project-name

Examples

# What a worktree has committed
wdx worktree diff --name auth-fix

# Everything not committed
wdx worktree diff --name auth-fix --uncommitted

# The uncommitted changes of a file
wdx worktree diff --name auth-fix --path internal/tide/tabs.go

# As JSON
wdx worktree diff --name auth-fix --project-name app --json

Output

The unified diff; nothing when nothing differs. With --json: {“worktree”: “…”, “patch”: “…”, …}

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`invalid_path`	1	the path cannot be used
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx worktree land

Land a worktree’s commits on its base, with no merge commit or through a PR.

wdx worktree land --name <worktree> [--method <method>] [--agent-id <id>] [--project-id <id> | --project-name <name>] [flags]

Rebases it if the base has moved on, undoing that on a conflict; runs the project’s check in a terminal named land-<worktree>, which stays if it fails; moves the base forward to the commit checked, and pushes it if the project says so. On any failure the base is where it was. This waits for the end, and leaving does not stop it. wdx project landing says how a project lands.

By PR it runs the check, pushes the branch and opens a PR with gh, or adds to the one open. It never rebases or forces, and the base stays where it is.

Flags

Flag	Default	Description
`--agent-id <id>`		id of the agent asking, which an agent finds in $WDX_AGENT_ID; it is not counted as working in the worktree
`--method <method>`		method for this landing, rebase or pr; what the project says when not given
`--name <name>`		name of the worktree
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

--name is required
at most one of --project-id or --project-name

Examples

# Land a worktree
wdx worktree land --name auth-fix

# Open a PR this once
wdx worktree land --name auth-fix --method pr

# From the agent working in it
wdx worktree land --name auth-fix --agent-id agent-1a2b3c4d

# As JSON
wdx worktree land --name auth-fix --project-name app --json

Output

What landed and on what, or the PR opened. With --json: {“result”: “landed”, “worktree”: “…”, …}

With --json, result is one of: landed, or pr_opened.

Errors

Code	Exit	When
`agent_working`	1	an agent is working in the worktree
`base_moved`	1	the base moved during the check
`check_failed`	1	the project’s check failed
`daemon_unavailable`	3	the daemon is not running or not answering
`dependency_missing`	3	a program the request needs is not installed: wdx deps list tells which
`detached_head`	1	the worktree is on no branch, so a PR has none to push
`fast_forward_failed`	1	git would not move the base forward
`invalid_path`	1	the path cannot be used
`land_not_configured`	1	the project has not said how it lands
`landing_running`	1	the worktree is already landing
`no_local_base`	1	the worktree has no local branch to land on
`not_committed`	1	the worktree has files not committed
`not_found`	1	nothing has this name or id
`nothing_to_land`	1	the worktree has nothing ahead of its base
`pr_failed`	1	gh did not open the pull request
`project_closed`	1	the project is closed
`push_failed`	1	git refused to push the branch
`rebase_failed`	1	the rebase stopped and was undone
`worktree_busy`	1	a rebase, a merge or the like is in progress in the worktree
`worktree_in_plan`	1	the worktree is a slot of a plan going on
`worktree_is_clone`	1	the project’s clone cannot be removed
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx worktree list

List every worktree git lists for a project, with its changes.

wdx worktree list [--project-id <id> | --project-name <name>] [flags]

Without a project flag, the project the working directory is in. Each worktree says how far it is ahead of its base, the default branch, and which files have uncommitted changes. One whose directory is gone is listed as missing.

Flags

Flag	Default	Description
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

at most one of --project-id or --project-name

Examples

# The worktrees of the project you are in
wdx worktree list

# Another project's, as JSON
wdx worktree list --project-name app --json

Output

The worktrees, the clone first, named main. With --json: {“worktrees”: […]}

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`invalid_path`	1	the path cannot be used
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx worktree rebase

Rebase a worktree onto its base, the default branch or a stacked plan’s plan below.

wdx worktree rebase --name <worktree> [--agent-id <id>] [--project-id <id> | --project-name <name>] [flags]

Landing’s rebase on its own: no check, and the base does not move. A conflict undoes it, leaving everything as it was, and lists the files; files not committed refuse it, as nothing is stashed. Either is for an agent to deal with: this sends nothing to one. A branch on origin is pushed again once rebased, over its commit there before the rebase only, never over another’s.

A stacked plan’s worktree asks gh whether the PR of the plan below has merged: if so, only the plan’s own commits move onto the default branch, and its PR goes there too, once the merge is pulled; if not, they move onto the plan below’s branch as it is now.

Flags

Flag	Default	Description
`--agent-id <id>`		id of the agent asking, which an agent finds in $WDX_AGENT_ID; it is not counted as working in the worktree
`--name <name>`		name of the worktree
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

--name is required
at most one of --project-id or --project-name

Examples

# Rebase a worktree
wdx worktree rebase --name auth-fix

# From the agent working in it
wdx worktree rebase --name auth-fix --agent-id agent-1a2b3c4d

# As JSON
wdx worktree rebase --name auth-fix --project-name app --json

Output

What it was rebased onto, or that it was up to date. With --json: {“result”: “rebased”, “worktree”: “…”, …}

With --json, result is one of: rebased, or up_to_date.

Errors

Code	Exit	When
`agent_working`	1	an agent is working in the worktree
`base_not_pulled`	1	the PR below is merged on GitHub, but not in the local default branch
`daemon_unavailable`	3	the daemon is not running or not answering
`dependency_missing`	3	a program the request needs is not installed: wdx deps list tells which
`detached_head`	1	the worktree is on no branch, so a PR has none to push
`invalid_path`	1	the path cannot be used
`no_local_base`	1	the worktree has no local branch to land on
`not_committed`	1	the worktree has files not committed
`not_found`	1	nothing has this name or id
`project_closed`	1	the project is closed
`push_failed`	1	git refused to push the branch
`rebase_failed`	1	the rebase stopped and was undone
`worktree_busy`	1	a rebase, a merge or the like is in progress in the worktree
`worktree_in_plan`	1	the worktree is a slot of a plan going on
`worktree_is_clone`	1	the project’s clone cannot be removed
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx worktree remove

Remove a worktree that landed, with its branch.

wdx worktree remove --name <worktree> [--project-id <id> | --project-name <name>] [flags]

Only one with nothing ahead of its base and nothing uncommitted, so no commit can be lost and nothing is asked; ignored files go with its directory. One whose directory is gone can always be removed: only git’s entry goes. The branch goes with it if git says it is merged. Agents running there are sent where to go on, and terminals running there are left as they are.

Flags

Flag	Default	Description
`--name <name>`		name of the worktree
`--project-id <id>`		id of the project (default: the one the working directory is in)
`--project-name <name>`		name of the project (default: the one the working directory is in)
`--node <name>`		run the command on the node of this name, another of your account, through a session

--name is required
at most one of --project-id or --project-name

Examples

# Remove a worktree that landed
wdx worktree remove --name auth-fix

# As JSON
wdx worktree remove --name auth-fix --project-name app --json

Output

What went, and who was told. With --json: {“result”: “removed”, “worktree”: “…”, …}

With --json, result is one of: removed.

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`invalid_path`	1	the path cannot be used
`not_found`	1	nothing has this name or id
`worktree_in_plan`	1	the worktree is a slot of a plan going on
`worktree_is_clone`	1	the project’s clone cannot be removed
`worktree_not_landed`	1	the worktree has commits or changes that have not landed
`worktree_not_removed`	1	git would not remove the worktree
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git