/bl-init - Git-Branchless Repository Initialization

Category: Git Workflow

Initialize git-branchless in the current repository, using the current branch as the main branch by default. Automatically detaches HEAD so you're ready to start stacking commits.

Usage

/bl-init [options]

Options

Option	Description
(none)	Initialize using current branch as main, then detach HEAD
--main-branch <branch>	Specify a different branch as main
--no-detach	Initialize without detaching HEAD

Examples

# Initialize with current branch as main
/bl-init

# Initialize with a specific branch as main
/bl-init --main-branch develop

Execution

This command delegates to the bl-init-expert agent:

Task(subagent_type="git-workflow:bl-init-expert",
     prompt="Initialize git-branchless: <options>")

Execution Instructions

1. Check Prerequisites

   • Verify this is a git repository
   • Check if git-branchless is installed
   • Check if already initialized

2. Determine Main Branch

   • Use current branch if no --main-branch specified
   • Validate the branch exists

3. Initialize Git-Branchless

   • Run git branchless init --main-branch <branch>
   • Configure recommended settings

4. Detach HEAD (unless --no-detach)

   • Run git checkout --detach
   • This prepares you for the stacked commits workflow

5. Verify Installation

   • Run git sl to confirm working
   • Show current state with detached HEAD

6. Provide Next Steps

   • Explain basic commands (git sl, git sync, git submit)

Interactive Flow

User: /bl-init

Agent: Initializing git-branchless...

Current branch: main
Repository: /path/to/project

Checking prerequisites...
✓ Git repository detected
✓ git-branchless is installed (v0.9.0)
✗ Not yet initialized

Initializing with main branch: main

$ git branchless init --main-branch main
Created config file at .git/branchless/config
Installed hooks at .git/hooks/
branchless: processing 1 update: main

Detaching HEAD for stacked workflow...
$ git checkout --detach

✓ Git-branchless initialized successfully!

Current state:
◆ abc1234 (main) Latest commit message
┃
● abc1234 (HEAD)  ← You are here (detached)

Ready to stack commits! Next steps:
1. Use `git record -m "msg"` to create commits
2. Use `git sl` to see your commit stack
3. Use `git sync --pull` to sync with remote
4. Use `git submit` to create/update PRs

User: /bl-init
(already initialized)

Agent: Checking git-branchless status...

✓ Git-branchless is already initialized in this repository.

Current main branch: main
Config file: .git/branchless/config

Current state:
◆ abc1234 (main) Latest commit
┃
◯ def5678 Your feature commit

To reinitialize with different settings:
1. Remove: rm -rf .git/branchless .git/hooks/post-*
2. Run: /bl-init again

User: /bl-init --main-branch develop

Agent: Initializing git-branchless with develop as main...

$ git branchless init --main-branch develop
Created config file at .git/branchless/config
Installed hooks at .git/hooks/
branchless: processing 1 update: develop

Detaching HEAD for stacked workflow...
$ git checkout --detach

✓ Git-branchless initialized with main branch: develop

User: /bl-init --no-detach

Agent: Initializing git-branchless (without detaching)...

$ git branchless init --main-branch main
Created config file at .git/branchless/config
Installed hooks at .git/hooks/
branchless: processing 1 update: main

✓ Git-branchless initialized successfully!

Current state:
◆ abc1234 (main) Latest commit message

Note: HEAD is still attached to main.
When ready to stack commits, run: git checkout --detach

Error Handling

Error	Resolution
Not a git repository	Run git init first
git-branchless not installed	Install with brew install git-branchless or cargo install git-branchless
Branch does not exist	List available branches, suggest correct one
Already initialized	Show current config, offer reinit instructions