Git Integration¶

Gira provides seamless Git integration to automatically track file operations using git mv and git rm, ensuring your project history accurately reflects all changes.

Overview¶

When working in a Git repository where the .gira directory is tracked, Gira can automatically stage file operations using Git commands. This includes:

Archiving tickets: Uses git mv to move files to archive
Deleting items: Uses git rm to remove files
Moving items: Uses git mv to track relocations
Closing sprints: Uses git mv to move to completed directory

Configuration¶

Automatic Detection¶

Gira automatically detects if your .gira directory is tracked by Git and enables Git operations by default.

Manual Configuration¶

You can control Git integration behavior using:

1. Command-line Flags¶

# Force git operations
gira ticket delete TEST-1 --git

# Disable git operations
gira ticket delete TEST-1 --no-git

2. Environment Variable¶

# Enable for all commands
export GIRA_AUTO_GIT_MV=true

# Disable for all commands
export GIRA_AUTO_GIT_MV=false

3. Configuration Settings¶

# Configure specific operations
gira config set git.auto_stage_moves true
gira config set git.auto_stage_archives true
gira config set git.auto_stage_deletes true

# View current settings
gira config get --list | grep git

Supported Commands¶

Ticket Operations¶

# Archive with git mv
gira ticket delete TEST-1

# Permanent delete with git rm
gira ticket delete TEST-1 --permanent

# Move between statuses (always uses git mv if tracked)
gira ticket move TEST-1 review

Sprint Operations¶

# Close sprint (moves to completed with git mv)
gira sprint close SPRINT-001

# Archive sprint with git mv
gira sprint delete SPRINT-001

# Permanent delete with git rm
gira sprint delete SPRINT-001 --permanent

Epic Operations¶

# Archive epic with git mv
gira epic delete EPIC-001

# Permanent delete with git rm
gira epic delete EPIC-001 --permanent

AI Agent Configuration¶

For AI agents and automation, we recommend:

# Set environment variable for consistent behavior
export GIRA_AUTO_GIT_MV=true

# Or configure globally
gira config set git.auto_stage_moves true
gira config set git.auto_stage_archives true
gira config set git.auto_stage_deletes true

Bulk Operations¶

When performing bulk operations (like archiving multiple tickets), Git operations are automatically used but warnings are suppressed to avoid spam:

# Archive all done tickets (uses git mv for each)
gira archive done --days 30

# Query and delete (uses git for each ticket)
gira query "status:done AND updated:<30d" | gira ticket delete -

Fallback Behavior¶

If a Git operation fails (e.g., file not tracked, permissions issue), Gira automatically falls back to regular file operations and displays a warning:

[yellow]Warning:[/yellow] Cannot use git mv - file is not tracked by git
[dim]Using regular file move instead[/dim]

Commit Workflow¶

After Gira operations that use Git, you can commit the changes:

# Archive tickets
gira ticket delete TEST-1 TEST-2 TEST-3

# Review staged changes
git status

# Commit with meaningful message
git commit -m "chore: archive completed tickets TEST-1, TEST-2, TEST-3"

Troubleshooting¶

Files Not Being Staged¶

Check if .gira is tracked:
```
git ls-files .gira
```

If not tracked, add it:

git add .gira
git commit -m "chore: track .gira directory"

Git Operations Failing¶

Check Git repository status:
```
git status
```
Ensure you have proper permissions:
```
ls -la .gira
```
Force regular operations if needed:
```
gira ticket delete TEST-1 --no-git
```

Configuration Not Working¶

Check current configuration:
```
gira config get git.auto_stage_moves
```
Verify environment variables:
```
echo $GIRA_AUTO_GIT_MV
```
Command-line flags always override other settings.

Best Practices¶

Initial Setup: Add .gira to Git tracking when initializing a project
Consistent Config: Use environment variables for automation
Review Changes: Always review git status before committing
Meaningful Commits: Use descriptive commit messages for Gira operations
Bulk Operations: Use queries and pipes for efficient bulk changes

Examples¶

Automated Sprint Cleanup¶

#!/bin/bash
# Close sprint and archive tickets

SPRINT_ID="SPRINT-2025-01"

# Close the sprint
gira sprint close $SPRINT_ID

# Archive all done tickets from the sprint
gira query "sprint:$SPRINT_ID AND status:done" | gira ticket delete -

# Commit all changes
git add .gira
git commit -m "chore: close $SPRINT_ID and archive completed tickets"

AI Agent Integration¶

import os
import subprocess

# Ensure git operations are enabled
os.environ['GIRA_AUTO_GIT_MV'] = 'true'

# Archive old tickets
subprocess.run(['gira', 'archive', 'done', '--days', '30'])

# Commit changes
subprocess.run(['git', 'add', '.gira'])
subprocess.run(['git', 'commit', '-m', 'chore: archive tickets older than 30 days'])