Skip to main content

Daily workflow

This is the core reason to use gji: you stop treating one checkout as shared mutable state for every task.

That becomes even more valuable when you work in parallel across your own changes, pull request review, and AI-assisted experiments.

Start a new feature​

gji new feature/auth-refactor

This creates:

  • a branch
  • a linked worktree
  • an immediate shell handoff when integration is enabled

If you use project hooks, this is also where install/setup automation typically runs.

To open the new worktree in an editor immediately:

gji new feature/auth-refactor --open --editor cursor

Once you have a saved editor (gji open --save), --editor is optional.

When starting a branch from work already committed in the current worktree, use --from-current:

gji new feature/auth-tests --from-current

Move in-progress changes into a new branch without a manual stash:

gji new feature/auth-take --take
gji new feature/auth-take-copy --take --copy

Open a pull request in isolation​

gji pr 1234
gji pr https://github.com/org/repo/pull/1234

This is useful when you are already mid-feature and want to review something without stashing or resetting your current checkout.

To return to the hosted PR page for the current worktree, run gji pr open. To choose another linked worktree, use --select, or target its branch/number directly:

gji pr open
gji pr open --select
gji pr open feature/auth-refactor
gji pr open '#1234'

Open a worktree in an editor​

gji open                              # open the current worktree in an editor
gji open --select                     # pick a worktree + editor interactively
gji open feature/auth-refactor        # open a specific branch
gji open --editor cursor --save       # use cursor and remember it

gji open opens the current worktree by default. Use --select when you want to choose another linked worktree without leaving your current task.

Move between active tasks​

gji go feature/auth-refactor
gji go repo-a/main
gji go main
gji back
gji root
gji ls
gji status

Use:

  • gji go to jump to any worktree by branch name or interactive selection; its chooser starts in the current repository and Tab includes all registered repositories
  • gji back to return to the last worktree you were in — like cd - but for worktrees
  • gji back 2 (or any number) to jump further back in history
  • gji history to see your full navigation history
  • gji ls for a detailed worktree list
  • gji ls --compact when you only need branch and path
  • gji status for health, branch state, and ahead/behind information
  • gji root when you just need the primary repo checkout again

Interactive worktree pickers show a worktree's task summary when one is set. Press / to search branch, path, PR, or task text; long task summaries are shortened to fit the terminal.

Use detached scratch space​

gji new --detached

Detached worktrees are useful when you want temporary investigation space without committing to a branch name yet.

Typical day example​

gji new feature/dark-mode
gji pr 184
gji go repo-a/main
gji go feature/dark-mode
gji back
gji sync
gji status
gji done
gji undo

Use gji done to finish one linked worktree. Use gji clean when you want to prune several worktrees; the older gji remove/rm commands remain available with a deprecation warning for compatibility.

The main point is that each task keeps its own files, dependencies, and terminal context.

Parallel work with AI​

If you use coding agents or AI-assisted tooling, worktrees stop being a nice-to-have and start becoming the clean boundary between tasks.

A common pattern looks like this:

gji new feature/checkout-redesign
gji pr 184
gji new --detached
gji ls

That gives you:

  • one worktree for your main implementation
  • one worktree for reviewing or reproducing a PR
  • one detached scratch space for agent-generated experiments or risky validation

Instead of asking one checkout to represent everything, you let each task keep its own state.