Contributing

Contributions are welcome! Here's how to get started.

Development Setup

1. Clone the repository:

   git clone https://github.com/basnijholt/trueloc.git
   cd trueloc
   

2. Install development dependencies:

   uv sync --group dev
   

3. Install pre-commit hooks:

   pre-commit install
   

Running Tests

pytest

Tests use respx to mock HTTP calls, so no GitHub API access is needed.

Code Quality

The project uses several tools to maintain code quality:

Linting

ruff check .
ruff format .

Type Checking

mypy .

All Checks

Pre-commit runs all checks automatically:

pre-commit run --all-files

Project Structure

src/trueloc/
├── cli.py       # Typer commands (count, count-local, clear-cache)
├── display.py   # Rich table formatting and JSON output
├── github.py    # GitHubClient - API calls with caching
├── local.py     # Local git repo analysis (git log/show)
├── models.py    # Pydantic-style dataclasses for stats
└── utils.py     # Shared utilities (cache, token, date parsing)

Pull Request Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes
4. Run tests and linting
5. Commit with a clear message
6. Push and open a PR

Tech Stack

• Python 3.12+
• Typer - CLI framework
• httpx - HTTP client
• Rich - Terminal output
• diskcache - Persistent caching
• dateparser - Flexible date parsing

License

By contributing, you agree that your contributions will be licensed under the MIT License.