| gh-wt

What are Actions?

Actions are commands that run automatically after a worktree is created. They can be used to open tmux sessions, launch editors, or run any other command.

Configuration

Action Schema

Each action supports the following fields:

Field	Type	Required	Description
`name`	string	Yes	Unique name for the action
`dir`	string	No	Working directory to run commands in. Supports template variables. Defaults to the worktree path.
`cmds`	[]string	Yes	List of commands to execute

Template Variables

Actions support the following template variables:

Variable	Description	Example
`{{.WorktreePath}}`	Path to the worktree	`~/github/worktree/pr_123`
`{{.WorktreeName}}`	Name of the worktree directory	`pr_123`
`{{.BranchName}}`	Name of the branch	`pr_123`
`{{.Action}}`	Name of the action being run	`tmux`
`{{.CLI_ARGS}}`	Arguments passed after `--`	`"fix bug"`
`{{.OS}}`	Operating system	`linux`
`{{.ARCH}}`	System architecture	`amd64`
`{{.ROOT_DIR}}`	Git root directory	`~/projects/my-repo`

Using Actions

Actions on Worktree Creation

Pass the -a or --action flag when creating a worktree:

gh wt add https://github.com/owner/repo/pull/123 -a tmux

You can also pass arguments to the action:

gh wt add my-branch -a editor -- --debug

The arguments after -- will be available in {{.CLI_ARGS}}.

Using Actions After Creation

Run actions on existing worktrees using the run command:

Run a Named Action

gh wt run pr_123 tmux

Run with Arguments

Pass arguments to the action using --:

gh wt run pr_123 editor -- --debug

Run a Command

Run any command directly in a worktree:

gh wt run pr_123 -- ls -la

Example Actions

VS Code

Opens the worktree directory in Visual Studio Code.

actions:
  - name: code
    dir: {{.WorktreePath}}
    cmds:
      - code .

tmux with Vim

Creates a new tmux session named after the branch and opens Vim in the worktree directory.

actions:
  - name: tmux-vim
    dir: {{.WorktreePath}}
    cmds:
      - tmux new-session -d -s {{.BranchName}}
      - tmux send-keys -t {{.BranchName}} "vim ." C-m

Shell in Worktree

Opens a new shell (using your default shell) in the worktree directory.

actions:
  - name: shell
    dir: {{.WorktreePath}}
    cmds:
      - $SHELL