Configuration

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 CLI uses a layered configuration system. Each layer overrides the previous:

1. Global config (~/.gitscrum/config.yml) — User-wide defaults
2. Project config (.gitscrum.yml) — Repository-specific settings
3. Environment variables — CI/CD overrides
4. Command-line flags — Per-command overrides

Global Configuration

Set user-wide defaults with gitscrum config set:

gitscrum config set workspace my-company
gitscrum config set project backend-api

View current configuration:

gitscrum config

Workspace: my-company
Project:   backend-api
API URL:   https://api.gitscrum.com

Configuration is stored in ~/.gitscrum/config.yml:

workspace: my-company
project: backend-api

Project Configuration (.gitscrum.yml)

Create a .gitscrum.yml in your repository root to share settings with your team:

gitscrum init -w my-company -p backend-api

Full Configuration Reference

# GitScrum CLI Project Configuration
# Commit this file to share settings with your team

version: "1"

# Required: Workspace and project association
workspace: my-company
project: backend-api

# Branch naming conventions
branch:
  # Prefix for new branches: feature, bugfix, hotfix, release
  default_prefix: feature
  
  # Include task title in branch name
  include_title: true
  
  # Maximum branch name length
  max_length: 60
  
  # Custom format: {prefix}, {code}, {title}
  format: "{prefix}/{code}-{title}"

# Timer configuration
timer:
  # Auto-start timer when switching to task branch
  auto_start: false
  
  # Auto-stop timer when switching away from task branch
  auto_stop: false
  
  # Round time entries to nearest interval (minutes)
  round_to: 15
  
  # Minimum duration to log (minutes)
  min_duration: 5
  
  # Remind to stop timer after inactivity (minutes)
  reminder_after: 120

# Git hooks integration
hooks:
  # Prepend task code to commit messages
  prepend_task_code: true
  
  # Commit message format (first %s = code, second %s = message)
  commit_format: "[%s] %s"
  
  # Validate task code exists before commit
  validate_task: false
  
  # Block commits without task code in branch name
  require_task_branch: false

# CI/CD automation rules
automation:
  # Update task status when PR is opened
  on_pr_open: in review
  
  # Update task status when PR is merged
  on_pr_merge: done
  
  # Link PRs to tasks based on branch name
  link_pr_to_task: true

# Default values for new tasks
defaults:
  type: task
  effort: 0
  priority: medium

Minimal Configuration

Only workspace and project are required:

version: "1"
workspace: my-company
project: backend-api

Environment Variables

Override configuration with environment variables:

Example: CI/CD Pipeline

export GITSCRUM_ACCESS_TOKEN="your-oauth-access-token"
export GITSCRUM_WORKSPACE="my-company"
export GITSCRUM_PROJECT="backend-api"

gitscrum tasks update GS-1234 --status "deployed"

Priority Order

1. Command-line flags (highest)
2. Environment variables
3. Project configuration (.gitscrum.yml)
4. Global configuration (~/.gitscrum/config.yml)
5. Built-in defaults (lowest)

Branch Naming

Configure how gitscrum tasks branch creates branch names:

branch:
  default_prefix: feature
  include_title: true
  max_length: 60
  format: "{prefix}/{code}-{title}"

Examples

Timer Configuration

Fine-tune time tracking behavior:

timer:
  auto_start: true     # Start timer on task branch checkout
  auto_stop: true      # Stop timer on branch switch
  round_to: 15         # Round to nearest 15 minutes
  min_duration: 5      # Ignore entries under 5 minutes
  reminder_after: 120  # Notify after 2 hours of inactivity

Rounding

When round_to: 15:

• 7 minutes → 15 minutes
• 23 minutes → 30 minutes
• 38 minutes → 45 minutes

Git Hooks

Enable automatic task code prepending to commit messages:

hooks:
  prepend_task_code: true
  commit_format: "[%s] %s"

Before:

git commit -m "Fix null pointer exception"

After:

[GS-1234] Fix null pointer exception

Setup

Install hooks in your repo:

gitscrum hooks install

This creates hooks in .git/hooks/ that integrate with your configuration.

Validation

Validate your configuration:

gitscrum config validate

Checks:

• YAML syntax
• Required fields present
• Valid workspace/project references
• Hook configuration

Configuration Files Location

File permissions are set to 0600 (owner read/write only) for security.