Git Integration

Open Source — GitScrum CLI is open source under the MIT license. Available on GitHub and all major package managers. Built for developers — Tasks, timers, sprints, and analytics in your terminal. Git-aware. CI/CD ready.

The GitScrum CLI is Git-aware by design. It reads your repository context to automatically link terminal commands to the right tasks and projects.

Automatic Branch Detection

The CLI detects your current Git branch and extracts task IDs automatically:

$ git checkout feature/GS-123-auth-refactor

$ gitscrum task current
# Matches task GS-123 from branch name

 📋 GS-123: Refactor authentication module
    Status: In Progress | Sprint 15
    Assignee: developer@company.com

How It Works

The CLI scans your branch name for common task ID patterns:

Supported Patterns

[prefix]/[TASK-ID]-[description]
[prefix]-[TASK-ID]-[description]
[TASK-ID]-[description]
[TASK-ID]

Common prefixes: feature, fix, hotfix, bugfix, chore, refactor

Branch Creation

Create branches with correct naming from task IDs:

$ gitscrum task branch GS-789

✓ Created branch: feature/GS-789-implement-oauth-flow
✓ Switched to branch

# Branch name derived from task title

Configuring Branch Format

Set your preferred branch format in .gitscrum.yml:

git:
  branch_format: "{type}/{id}-{slug}"
  default_type: feature
  max_slug_length: 50

Available placeholders:

Examples:

# Output: feature/GS-123-implement-oauth
branch_format: "{type}/{id}-{slug}"

# Output: john/GS-123
branch_format: "{user}/{id}"

# Output: GS-123-implement-oauth
branch_format: "{id}-{slug}"

Commit Message Integration

Format commit messages with task IDs:

$ git commit -m "$(gitscrum task current --format '[{id}] {title}')"
# Commits with: [GS-123] Implement OAuth flow

Commit Hooks

Install Git hooks for automatic commit formatting:

gitscrum hooks install --commit-msg

This adds a commit-msg hook that:

1. Detects task ID from branch name
2. Prepends task ID to commit message if missing
3. Validates message format (optional)

Example flow:

$ git checkout feature/GS-123-oauth
$ git commit -m "add token refresh logic"
# Hook transforms to: [GS-123] add token refresh logic

Git Hooks

The CLI can install automation hooks:

gitscrum hooks install [hook-type]

Available Hooks

Installation Examples

# Install single hook
gitscrum hooks install commit-msg

# Install all hooks
gitscrum hooks install --all

# Preview without installing
gitscrum hooks install commit-msg --dry-run

Hook Behavior

commit-msg

# Before: "fix validation bug"
# After:  "[GS-123] fix validation bug"

Configuration:

hooks:
  commit_msg:
    enabled: true
    format: "[{id}] "  # Prefix format
    skip_if_present: true  # Don't add if ID exists

pre-push

hooks:
  pre_push:
    enabled: true
    start_timer: false  # Start timer on push
    update_status: true  # Set task to "In Progress"

post-checkout

hooks:
  post_checkout:
    enabled: true
    switch_timer: true  # Switch timer to new branch's task
    show_task: true     # Display task info after checkout

Managing Hooks

# List installed hooks
gitscrum hooks list

# Remove specific hook
gitscrum hooks remove commit-msg

# Remove all GitScrum hooks
gitscrum hooks remove --all

Repository Detection

The CLI automatically detects your Git repository context:

$ cd /path/to/my-project
$ git remote -v
origin	git@github.com:company/my-project.git

$ gitscrum task list
# Uses project linked to github.com/company/my-project

Linking Repository to Project

First-time setup links your repo to a GitScrum project:

$ gitscrum init

? Select project: My Project (GS)
? Link to repository: github.com/company/my-project

✓ Created .gitscrum.yml
✓ Repository linked to project "My Project"

This creates .gitscrum.yml:

project: my-project
repository: github.com/company/my-project

Multiple Remotes

If you have multiple remotes, specify which to use:

git:
  remote: upstream  # Default: origin

Worktree Support

The CLI works with Git worktrees:

$ git worktree add ../feature-GS-123 feature/GS-123

$ cd ../feature-GS-123
$ gitscrum task current
# Correctly detects GS-123 from worktree branch

Each worktree can have its own timer running.

Shallow Clones

The CLI works with shallow clones (common in CI):

$ git clone --depth 1 https://github.com/company/repo.git
$ cd repo
$ gitscrum task list
# Works normally

Branch detection still works, but some features requiring full history may be limited.

Monorepo Support

For monorepos with multiple projects:

repo/
├── packages/
│   ├── api/
│   │   └── .gitscrum.yml  # project: api-backend
│   └── web/
│       └── .gitscrum.yml  # project: web-frontend
└── .gitscrum.yml          # project: monorepo (root)

The CLI uses the nearest .gitscrum.yml:

$ cd packages/api
$ gitscrum task list
# Lists tasks from api-backend project

$ cd ../..
$ gitscrum task list
# Lists tasks from monorepo project

Environment Variables

Override Git detection with environment variables:

Useful in CI where Git context may be limited:

export GITSCRUM_BRANCH="${CI_COMMIT_REF_NAME}"
gitscrum task current

Troubleshooting

Branch Not Detected

$ gitscrum task current
Error: Not in a Git repository

# Solution: Ensure you're in a Git repo
$ git status

Task ID Not Extracted

$ gitscrum task current
Warning: No task ID found in branch name

# Solution: Use standard branch naming
$ git checkout -b feature/GS-123-my-feature

Wrong Project Detected

$ gitscrum task list
Warning: Project "old-project" not found

# Solution: Re-run init or update .gitscrum.yml
$ gitscrum init --force