GitDo

Simple CLI tool to plan your work. Tasks are stored locally in a .gitdo/ folder.

Installation

pip install gitdo

Usage

$ gitdo [command] [options]

Commands

• init: Initialize a new GitDo project
• add <task>: Add a new task to your project
• list: List tasks (by default shows pending and in-progress tasks)
  • --status/-s <status>: Filter by status (pending, inprogress, completed)
  • --all/-a: Show all tasks regardless of status
• start <task_id>: Mark a task as in progress
• complete <task_id>: Mark a task as completed
• remove <task_id>: Remove a task from your project
• import-md <file_path>: Import tasks from a markdown file
  • --skip-duplicates: Skip tasks with duplicate titles
  • --dry-run: Preview tasks without importing

Task Statuses

Tasks can have one of three statuses:

• pending: Task has been created but not started
• inprogress: Task is currently being worked on
• completed: Task has been finished

Example

# Initialize GitDo in your project
$ gitdo init
✓ GitDo initialized successfully!# Add some tasks
$ gitdo add "Implement user authentication"
✓ Added task: Implement user authentication
ID: a1b2c3d4
$ gitdo add "Write unit tests"
✓ Added task: Write unit tests
ID: e5f6g7h8
$ gitdo add "Update documentation"
✓ Added task: Update documentation
ID: i9j0k1l2
# List all pending and in-progress tasks (default)
$ gitdo list
# Start working on a task
$ gitdo start a1b2
✓ Task a1b2 marked as in progress!# List only in-progress tasks
$ gitdo list --status inprogress
# Complete a task (you can use just the first few characters of the ID)
$ gitdo complete a1b2
✓ Task a1b2 marked as completed!# List all tasks including completed ones
$ gitdo list --all
# List only completed tasks
$ gitdo list --status completed
# Remove a task
$ gitdo remove e5f6
✓ Task e5f6 removed!# Import tasks from a markdown file
$ gitdo import-md tasks.md
✓ Imported 5 task(s)
# Preview tasks before importing
$ gitdo import-md tasks.md --dry-run

Development

Setup

This project uses uv for dependency management.

1. Install uv:

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone the repository:

   git clone https://github.com/yourusername/gitdo.git
   cd gitdo

3. Install dependencies:

   uv sync --extra dev

Running Tests

# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=gitdo --cov-report=html
# Run specific test file
uv run pytest tests/test_cli.py
# Run tests in watch mode (requires pytest-watch)
uv run ptw

Code Quality

This project uses Ruff for linting and formatting:

# Check code
uv run ruff check .# Format code
uv run ruff format .# Check and fix
uv run ruff check --fix .

Project Structure

gitdo/
├── src/
│ └── gitdo/
│ ├── __init__.py
│ ├── cli.py # CLI interface
│ ├── models.py # Data models
│ └── storage.py # Storage handling
├── tests/
│ ├── conftest.py # Pytest fixtures
│ ├── test_cli.py # CLI tests
│ ├── test_models.py # Model tests
│ └── test_storage.py # Storage tests
├── pyproject.toml # Project configuration
└── README.md

Releasing to PyPI

This project uses GitHub Actions for automated publishing to PyPI. Releases are triggered by pushing version tags.

Automated Release (Recommended)

Use the release script to create a new version:

# Create a new release (e.g., 0.2.0)
./scripts/release.sh 0.2.0
# Push to trigger the release
git push origin main --tags

The script will:

1. Update version in pyproject.toml and __init__.py
2. Create a git commit
3. Create a version tag (e.g., v0.2.0)

When you push the tag, GitHub Actions will:

1. Extract version from the tag
2. Build the package
3. Publish to PyPI using Trusted Publishing

Manual Build (Testing)

# Build the package locally
uv build
# Check the built package
ls -la dist/

License

MIT