git

package
v1.9.29 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 21, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package git provides git worktree operations for agent-deck

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BranchExists 

func BranchExists(repoDir, branchName string) bool

BranchExists checks if a branch exists in the repository

func CreateWorktree 

func CreateWorktree(repoDir, worktreePath, branchName string) error

CreateWorktree creates a new git worktree at worktreePath for the given branch If the branch doesn't exist, it will be created

func CreateWorktreeWithSetup added in v1.3.1 

func CreateWorktreeWithSetup(repoDir, worktreePath, branchName string, stdout, stderr io.Writer, setupTimeout time.Duration) (setupErr error, err error)

CreateWorktreeWithSetup creates a worktree and runs the setup script if present. Setup script failure is non-fatal: the worktree is still valid. Output is streamed to the provided writers. A non-positive setupTimeout means "no deadline" — see RunWorktreeSetupScript for the full semantic.

User-visible progress (#768): the start preamble, an explicit completion line on success, and an explicit failure line on error are written to stderr so callers (CLI streaming directly, TUI capturing into a buffer for later display) can show the user what happened. Without these, users couldn't tell whether the script had run, finished, or finished cleanly before claude started.

func CreateWorktreeWithStateAndSetup added in v1.9.15 

func CreateWorktreeWithStateAndSetup(repoDir, worktreePath, branchName string, state WorktreeStateOptions, stdout, stderr io.Writer, setupTimeout time.Duration) (setupErr error, err error)

CreateWorktreeWithStateAndSetup is CreateWorktreeWithSetup plus optional materialization of the parent session's working-tree state (#1029). Materialization happens BEFORE worktreeinclude processing and the setup script so both observe the realized state, per @smorin's spec.

func DeleteBranch added in v0.10.20 

func DeleteBranch(repoDir, branchName string, force bool) error

DeleteBranch deletes a local branch. If force is true, uses -D (force delete).

func FindWorktreeSetupScript added in v1.3.1 

func FindWorktreeSetupScript(repoDir string) (string, os.FileMode)

FindWorktreeSetupScript returns the path to the worktree setup script if one exists at <repoDir>/.agent-deck/worktree-setup.sh, or empty string. The returned os.FileMode captures the file's permission bits at discovery time, eliminating a TOCTOU race between finding and dispatching the script.

func GeneratePathID added in v0.10.10 

func GeneratePathID() string

GeneratePathID returns an 8-character random hex string for path uniqueness. Used to provide a unique identifier in worktree path templates via {session-id}.

func GenerateWorktreePath 

func GenerateWorktreePath(repoDir, branchName, location string) string

GenerateWorktreePath generates a worktree directory path based on the repository directory, branch name, and location strategy. Location "subdirectory" places worktrees under <repo>/.worktrees/<branch>. Location "sibling" (or empty) places worktrees as <repo>-<branch> alongside the repo. A custom path (containing "/" or starting with "~") places worktrees at <path>/<repo_name>/<branch>.

True-bare-at-root layout overrides the sibling/subdirectory defaults: linked worktrees live as direct children of the bare dir (<repo>/<branch>), since neither default makes sense when the project root *is* the bare repo. Custom path templates still take precedence (see WorktreePath in template.go).

func GetCurrentBranch 

func GetCurrentBranch(dir string) (string, error)

GetCurrentBranch returns the current branch name for the repository at dir

func GetDefaultBranch added in v0.10.20 

func GetDefaultBranch(repoDir string) (string, error)

GetDefaultBranch returns the default branch name (e.g. "main" or "master") for the repo

func GetMainWorktreePath 

func GetMainWorktreePath(dir string) (string, error)

GetMainWorktreePath returns the path to the "project root" — the directory that hosts shared config like .agent-deck/.

  • Normal repo: the repo root (parent of .git/).
  • Linked worktree of a normal repo: the main worktree (parent of .git/).
  • Nested ".bare/" layout (issue #715): the parent of .bare/. There is no "main" worktree; every linked worktree is equal, shared config lives next to .bare/.
  • True-bare-at-root layout: the bare repo dir itself (e.g. "kslifeinc.git"). Linked worktrees live as direct children, shared config lives inside.

func GetRepoRoot 

func GetRepoRoot(dir string) (string, error)

GetRepoRoot returns the root directory of the git repository containing dir

func GetWorktreeBaseRoot added in v0.17.0 

func GetWorktreeBaseRoot(dir string) (string, error)

GetWorktreeBaseRoot returns the "project root" suitable for locating shared config (.agent-deck/, setup scripts, etc.). Accepts:

  • A normal repo dir → repo root.
  • A linked worktree → the main worktree (or, for bare-repo layouts, the parent of .bare/ or the bare-at-root dir itself).
  • A nested-bare project root (no .git but contains .bare/) → that root.
  • A bare-at-root project root → the bare dir itself.

This guarantees that downstream .agent-deck/ lookups resolve to a single stable location regardless of which worktree (or the project root) the caller started from.

func GetWorktreeForBranch 

func GetWorktreeForBranch(repoDir, branchName string) (string, error)

GetWorktreeForBranch returns the worktree path for a given branch, if any

func HasUncommittedChanges added in v0.10.20 

func HasUncommittedChanges(dir string) (bool, error)

HasUncommittedChanges checks if the repository at dir has uncommitted changes

func IsBareRepo added in v1.7.58 

func IsBareRepo(dir string) bool

IsBareRepo returns true if dir itself is a bare git repository. For a linked worktree checkout, this returns false — use IsBareRepoWorktree for that case.

func IsBareRepoAtRoot added in v1.9.11 

func IsBareRepoAtRoot(dir string) bool

IsBareRepoAtRoot returns true if dir is a bare repository serving as the project root itself (linked worktrees live as direct children inside it). False for normal repos, linked worktrees, and the nested ".bare/" layout.

Uses isBareRepoSelf rather than IsBareRepo to filter the same false-positive class that findNestedBareRepo addresses: `git rev-parse --is-bare-repository` reports true for any descendant of a bare repo via parent discovery, so `IsBareRepoAtRoot("/repo.git/hooks")` would otherwise return true (basename "hooks" ≠ ".bare", and IsBareRepo says it's bare). isBareRepoSelf confirms the candidate is itself the bare repo.

func IsBareRepoWorktree added in v1.7.58 

func IsBareRepoWorktree(dir string) bool

IsBareRepoWorktree returns true if dir is a linked worktree whose shared git-common-dir is itself a bare repository — covers both the nested ".bare/" pattern from issue #715 and the bare-at-root layout. In either case there is no "main" worktree; every linked worktree is equal.

func IsGitRepo 

func IsGitRepo(dir string) bool

IsGitRepo checks if the given directory is inside a git repository

func IsGitRepoOrBareProjectRoot added in v1.7.58 

func IsGitRepoOrBareProjectRoot(dir string) bool

IsGitRepoOrBareProjectRoot returns true if dir is either a regular git directory (normal repo, linked worktree, or a bare repo) or the project root of a bare-repo layout (contains a nested bare repo such as .bare/). Callers that need to validate "is this a path agent-deck can launch a session from?" should prefer this over IsGitRepo.

func IsWorktree 

func IsWorktree(dir string) bool

IsWorktree checks if the given directory is a git worktree (not the main repo)

func ListBranchCandidates added in v0.27.0 

func ListBranchCandidates(repoDir string) ([]string, error)

ListBranchCandidates returns unique branch names from local branches and the default remote, normalized to plain branch names without a remote prefix.

func MaterializeWipFromParent added in v1.9.15 

func MaterializeWipFromParent(parentDir, childDir string, includeIgnored bool) error

MaterializeWipFromParent copies the working-tree state of parentDir (staged changes, unstaged edits, and untracked files) into childDir, which must be a freshly-created worktree pointing at parentDir's HEAD. When includeIgnored is true, gitignored files are also copied.

Contract:

  • parentDir is treated read-only — no stash push, no add, no index mutation.
  • childDir's `git status --porcelain` becomes equal to parentDir's `git status --porcelain` after this call.
  • Refuses to run when parent is in mid-rebase / merge / cherry-pick / revert / bisect.

Implements issue #1029 (--with-state / --with-state-and-gitignored).

func MergeBack added in v1.9.6 

func MergeBack(projectRoot, sourceBranch, targetBranch string) error

MergeBack merges sourceBranch into targetBranch, handling both regular and bare-repository layouts.

In a regular layout, projectRoot is a working tree: this is the historical path — `git checkout targetBranch` then `git merge sourceBranch`.

In a bare-repo layout (issue #715/#891), projectRoot is the parent of a nested bare repo (typically `.bare/`). The bare dir has no working tree, so `checkout`/`merge` cannot run there directly. Instead:

  • If targetBranch is an ancestor of sourceBranch (fast-forward case), advance targetBranch via `update-ref` on the bare dir.
  • Otherwise, create a throwaway worktree of targetBranch, perform the merge there, then remove the worktree.

Regression test: TestWorktree_MergeBack_BareRepo_RegressionFor891.

func MergeBranch added in v0.10.20 

func MergeBranch(repoDir, branchName string) error

MergeBranch merges the given branch into the current branch of the repository

func ProcessWorktreeInclude added in v1.9.2 

func ProcessWorktreeInclude(repoDir, worktreePath string, stderr io.Writer) error

ProcessWorktreeInclude copies gitignored files matching patterns in .worktreeinclude from repoDir into worktreePath. Returns nil if no .worktreeinclude exists.

Matches Claude Code Desktop behavior: https://code.claude.com/docs/en/worktrees#copy-gitignored-files-into-worktrees

func PruneWorktrees added in v0.10.20 

func PruneWorktrees(repoDir string) error

PruneWorktrees removes stale worktree references

func RemoveWorktree 

func RemoveWorktree(repoDir, worktreePath string, force bool) error

RemoveWorktree removes a worktree from the repository. If force is true, it will remove even if there are uncommitted changes. When force is true and git fails (e.g. "Directory not empty" due to untracked files like node_modules), falls back to removing the directory directly and pruning stale worktree references.

func RunWorktreeSetupScript added in v1.3.1 

func RunWorktreeSetupScript(scriptPath string, scriptMode os.FileMode, repoDir, worktreePath string, stdout, stderr io.Writer, timeout time.Duration) error

RunWorktreeSetupScript executes the setup script with AGENT_DECK_REPO_ROOT and AGENT_DECK_WORKTREE_PATH environment variables set. Working directory is set to worktreePath. Output is streamed to the provided writers.

Dispatch (#773):

  • If scriptPath has the user-executable bit set, the script is invoked directly so the kernel honors its shebang line (e.g. #!/usr/bin/env bash, #!/usr/bin/env python3). This lets users write the setup script in any language they like.
  • Otherwise (legacy 0644 setups predating #773), fall back to `sh -e <path>` so existing repos keep working without a chmod.

Timeout semantics (post-#727 follow-up):

  • timeout > 0 → bounded by context.WithTimeout
  • timeout <= 0 → unlimited (context.Background, no deadline)

The session layer resolves the legacy 60s default before calling here; callers that want bounded runs must pass a positive duration explicitly.

func SanitizeBranchName 

func SanitizeBranchName(name string) string

SanitizeBranchName converts a string to a valid branch name

func ValidateBranchName 

func ValidateBranchName(name string) error

ValidateBranchName validates that a branch name follows git's naming rules

func WorktreePath added in v0.10.10 

func WorktreePath(opts WorktreePathOptions) string

WorktreePath generates a worktree path. If opts.Template is set, it expands the template with variables:

  • {repo-name}, {repo-root}, {session-id}
  • {branch}: sanitized (human-friendly, may collide)
  • {branch-escaped}: URL-escaped (collision-resistant, reversible)

Unknown variables like {foo} are left as-is in the resolved path. Falls back to location-based strategy using opts.Location when template is empty or RepoDir is invalid.

Types

type Worktree 

type Worktree struct {
	Path   string // Filesystem path to the worktree
	Branch string // Branch name checked out in this worktree
	Commit string // HEAD commit SHA
	Bare   bool   // Whether this is the bare repository
}

Worktree represents a git worktree

func ListWorktrees 

func ListWorktrees(repoDir string) ([]Worktree, error)

ListWorktrees returns all worktrees for the repository at repoDir

type WorktreePathOptions added in v0.10.10 

type WorktreePathOptions struct {
	Branch    string
	Location  string
	RepoDir   string
	SessionID string
	Template  string
}

WorktreePathOptions configures worktree path generation.

type WorktreeStateOptions added in v1.9.15 

type WorktreeStateOptions struct {
	// WithState copies parent's staged/unstaged/untracked files into the
	// new worktree before the setup hook runs.
	WithState bool
	// WithIgnored, when WithState is true, also copies parent's gitignored
	// files (e.g., .env, .mcp.json). Implies WithState.
	WithIgnored bool
}

WorktreeStateOptions controls the issue #1029 with-state behavior of CreateWorktreeWithStateAndSetup. When WithState is false, the worktree is created clean from branch tip — the legacy behavior.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.