git donkey

Create a linked worktree at ../{repo}.worktrees/{branch}. When no base is specified, the command discovers the default branch advertised by the principal remote and creates the new branch from its fetched remote commit. The principal remote is the first configured remote, preserving the existing selection rule. The default branch need not be named main, and the remote need not be named origin.

The command fetches remote references but does not pull, rebase, or prompt to update a local base by default. Unpublished local commits and uncommitted changes in the primary checkout are not used as the implicit base. An unavailable remote default produces an error asking for an explicit base; the command never silently falls back to local main.

A named base still selects that branch. . selects the branch checked out in the calling working directory, including when called from a linked worktree. Existing local or remote feature branches are reused with their existing tracking rules; the base is used only when creating a new branch. If the worktree path already exists or the branch is already checked out elsewhere, the command exits with a ⚔️ conflict message.

# Create from the principal remote's default branch without updating checkouts

git donkey feature/foo

# Use the calling worktree's local branch, including its local commits

git donkey feature/foo .

# Create from a specific base without pulling it

git donkey feature/foo release/1.2

# Enable the existing confirmation workflow for pull plus rebase

git donkey feature/foo release/1.2 --pull-rebase

# Enable the same workflow, permitting only a fast-forward update

git donkey feature/foo release/1.2 --pull-ff

Options:

• --pull-rebase enables a prompt to run git pull --rebase when the local base is behind its remote counterpart.
• --pull-ff enables that prompt using git pull --no-rebase --ff-only. Divergent histories fail rather than being merged or rebased, regardless of configured pull preferences.
• --no-pull remains supported for compatibility and explicitly selects the new default behaviour. Fetching remote references still occurs.

These three options are mutually exclusive. A declined prompt, or a non-interactive terminal, skips the update as before. A local-only base has no remote update to perform. An approved update runs only in the worktree holding the selected local base; if that branch is not checked out, the command fails rather than updating an unrelated primary-checkout branch.

With an omitted base, an enabled pull option may update the corresponding local default branch, but the new feature branch still starts at the remote commit. Supply the local base explicitly, or use ., to include local commits after an approved update.

The default-base and pull-mode design records the discovery, preservation, and verification contracts. The 0.2.0 migration guide documents the behaviour changes for users upgrading from 0.1.0.

After creating the worktree, git donkey automatically applies template overlay files if a template directory exists for the repository. Template directories are stored under the platform-specific user data directory for git-donkey:

<user-data-dir>/git-donkey/template/<repo-url-slug>

The slug format is <slugified-text>-<adler32-checksum>, where the checksum provides collision resistance while the slugified text remains human-readable.

Use git donkey-template within a repository to display and create the template directory path:

cd ~/projects/myrepo
git donkey-template
# Template directory: /path/to/user-data/git-donkey/template/myrepo-a1b2c3d4

When a template exists, all files from the template directory are copied into the newly created worktree. If a file already exists in the worktree, a warning is issued, but the file is overwritten. This design allows maintaining per-repository configuration files (such as .editorconfig, .vscode/settings.json, or project-specific configurations) and automatically applying them to all new worktrees.

Example template structure:

<user-data-dir>/git-donkey/template/
  myrepo-a1b2c3d4/
    .editorconfig
    .vscode/
      settings.json
    config/
      local.json

On other platforms, the template directory follows the platform's conventions for user data storage (e.g., ~/.local/share/git-donkey/template on Linux or ~/Library/Application Support/git-donkey/template on macOS).