|
| 1 | +# Copilot Instructions for Gitoxide |
| 2 | + |
| 3 | +This repository contains `gitoxide` - a pure Rust implementation of Git. This document provides guidance for GitHub Copilot when working with this codebase. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +- **Language**: Rust (MSRV documented in gix/Cargo.toml) |
| 8 | +- **Structure**: Cargo workspace with multiple crates (gix-*, gitoxide-core, etc.) |
| 9 | +- **Main crates**: `gix` (library entrypoint), `gitoxide` binary (CLI tools: `gix` and `ein`) |
| 10 | +- **Purpose**: Provide a high-performance, safe Git implementation with both library and CLI interfaces |
| 11 | + |
| 12 | +## Development Practices |
| 13 | + |
| 14 | +### Test-First Development |
| 15 | +- Protect against regression and make implementing features easy |
| 16 | +- Keep it practical - the Rust compiler handles mundane things |
| 17 | +- Use git itself as reference implementation; run same tests against git where feasible |
| 18 | +- Never use `.unwrap()` in production code, avoid it in tests in favor of `.expect()` or `?`. Use `gix_testtools::Result` most of the time. |
| 19 | +- Use `.expect("why")` with context explaining why expectations should hold, but only if it's relevant to the test. |
| 20 | + |
| 21 | +### Error Handling |
| 22 | +- Handle all errors, never `unwrap()` |
| 23 | +- Provide error chains making it easy to understand what went wrong |
| 24 | +- Use `thiserror` for libraries generally |
| 25 | +- Binaries may use `anyhow::Error` exhaustively (user-facing errors) |
| 26 | + |
| 27 | +### Commit Messages |
| 28 | +Follow "purposeful conventional commits" style: |
| 29 | +- Use conventional commit prefixes ONLY if message should appear in changelog |
| 30 | +- Breaking changes MUST use suffix `!`: `change!:`, `remove!:`, `rename!:` |
| 31 | +- Features/fixes visible to users: `feat:`, `fix:` |
| 32 | +- Refactors/chores: no prefix (don't affect users) |
| 33 | +- Examples: |
| 34 | + - `feat: add Repository::foo() to do great things. (#234)` |
| 35 | + - `fix: don't panic when calling foo() in a bare repository. (#456)` |
| 36 | + - `change!: rename Foo to Bar. (#123)` |
| 37 | + |
| 38 | +### Code Style |
| 39 | +- Follow existing patterns in the codebase |
| 40 | +- No `.unwrap()` - use `.expect("context")` if you are sure this can't fail. |
| 41 | +- Prefer references in plumbing crates to avoid expensive clones |
| 42 | +- Use `gix_features::threading::*` for interior mutability primitives |
| 43 | + |
| 44 | +### Path Handling |
| 45 | +- Paths are byte-oriented in git (even on Windows via MSYS2 abstraction) |
| 46 | +- Use `gix::path::*` utilities to convert git paths (`BString`) to `OsStr`/`Path` or use custom types |
| 47 | + |
| 48 | +## Building and Testing |
| 49 | + |
| 50 | +### Quick Commands |
| 51 | +- `just test` - Run all tests, clippy, journey tests, and try building docs |
| 52 | +- `just check` - Build all code in suitable configurations |
| 53 | +- `just clippy` - Run clippy on all crates |
| 54 | +- `cargo test` - Run unit tests only |
| 55 | + |
| 56 | +### Build Variants |
| 57 | +- `cargo build --release` - Default build (big but pretty, ~2.5min) |
| 58 | +- `cargo build --release --no-default-features --features lean` - Lean build (~1.5min) |
| 59 | +- `cargo build --release --no-default-features --features small` - Minimal deps (~46s) |
| 60 | + |
| 61 | +### Test Best Practices |
| 62 | +- Run tests before making changes to understand existing issues |
| 63 | +- Use `GIX_TEST_IGNORE_ARCHIVES=1` when testing on macOS/Windows |
| 64 | +- Journey tests validate CLI behavior end-to-end |
| 65 | + |
| 66 | +## Architecture Decisions |
| 67 | + |
| 68 | +### Plumbing vs Porcelain |
| 69 | +- **Plumbing crates**: Low-level, take references, expose mutable parts as arguments |
| 70 | +- **Porcelain (gix)**: High-level, convenient, may clone Repository for user convenience |
| 71 | +- Platforms: cheap to create, keep reference to Repository |
| 72 | +- Caches: more expensive, clone `Repository` or free of lifetimes |
| 73 | + |
| 74 | +### Options vs Context |
| 75 | +- Use `Options` for branching behavior configuration (can be defaulted) |
| 76 | +- Use `Context` for data required for operation (cannot be defaulted) |
| 77 | + |
| 78 | +## Crate Organization |
| 79 | + |
| 80 | +### Common Crates |
| 81 | +- `gix`: Main library entrypoint (porcelain) |
| 82 | +- `gix-object`, `gix-ref`, `gix-config`: Core git data structures |
| 83 | +- `gix-odb`, `gix-pack`: Object database and pack handling |
| 84 | +- `gix-diff`, `gix-merge`, `gix-status`: Operations |
| 85 | +- `gitoxide-core`: Shared CLI functionality |
| 86 | + |
| 87 | +## Documentation |
| 88 | +- High-level docs: README.md, CONTRIBUTING.md, DEVELOPMENT.md |
| 89 | +- Crate status: crate-status.md |
| 90 | +- Stability guide: STABILITY.md |
| 91 | +- Always update docs if directly related to code changes |
| 92 | + |
| 93 | +## CI and Releases |
| 94 | +- Ubuntu-latest git version is the compatibility target |
| 95 | +- `cargo smart-release` for releases (driven by commit messages) |
| 96 | +- Split breaking changes into separate commits per affected crate if one commit-message wouldn't be suitable for all changed crates. |
| 97 | +- First commit: breaking change only; second commit: adaptations |
| 98 | + |
| 99 | +## When Suggesting Changes |
| 100 | +1. Understand the plumbing vs porcelain distinction |
| 101 | +2. Check existing patterns in similar crates |
| 102 | +3. Follow error handling conventions strictly |
| 103 | +4. Ensure changes work with feature flags (small, lean, max, max-pure) |
| 104 | +5. Consider impact on both library and CLI users |
| 105 | +6. Test against real git repositories when possible |
0 commit comments