Glassthought

Notes for 'git worktree list --porcelain'

1 min read

Branch

Git Worktree Branch Naming from Porcelain Output

When using git worktree list --porcelain, the branch field contains different formats depending on the worktree state.

Key Points

  • The refs/heads/ prefix indicates a local branch
  • The refs/remotes/ prefix indicates a remote-tracking branch
  • Special states use flags (detached, bare) instead of branch names
  • This follows Git’s internal reference storage structure

Branch Field Formats

Local Branches

branch refs/heads/feature-branch
  • Format: refs/heads/<branch-name>
  • When: Worktree is checked out to a local branch
  • Example: refs/heads/main, refs/heads/develop

Remote Tracking Branches

branch refs/remotes/origin/feature-branch
  • Format: refs/remotes/<remote>/<branch-name>
  • When: Worktree is tracking a remote branch
  • Example: refs/remotes/origin/main

Special States

Detached HEAD

detached
  • Field: No branch field, instead has detached flag
  • When: HEAD points to specific commit, not a branch
  • Example: After git checkout <commit-hash>

Bare Repository

bare
  • Field: No branch field, instead has bare flag
  • When: Repository has no working directory
  • Example: Central repositories, .git directories

Unknown State

branch unknown
  • Format: unknown
  • When: Branch information cannot be determined
  • Example: Corrupted repository state

Reference Storage

Git stores references in a hierarchical namespace:

  • refs/heads/ - Local branches
  • refs/remotes/ - Remote-tracking branches
  • refs/tags/ - Tags
  • refs/stash/ - Stash entries
Link to original

Graph View