{"owner":"GitoxideLabs","repo":"gitoxide","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Copilot Instructions for Gitoxide\n\nThis repository contains `gitoxide` - a pure Rust implementation of Git. This document provides guidance for GitHub Copilot when working with this codebase.\n\n## Project Overview\n\n- **Language**: Rust (MSRV documented in gix/Cargo.toml)\n- **Structure**: Cargo workspace with multiple crates (gix-\\*, gitoxide-core, etc.)\n- **Main crates**: `gix` (library entrypoint), `gitoxide` binary (CLI tools: `gix` and `ein`)\n- **Purpose**: Provide a high-performance, safe Git implementation with both library and CLI interfaces\n\n## Development Practices\n\n### AI Agent Communication\n\n- AI agents communicating through a person's account must identify themselves, for example in issue or PR descriptions and comments.\n- AI assistance that does not replace the person as the speaker, such as proofreading or wording polish, does not require identification.\n- Attributing AI assistance in commit metadata, for example with an `Assisted-by:` or `Co-authored-by:` trailer, is welcome but not required.\n\n### Test-First Development\n\n- Protect against regression and make implementing features easy\n- Keep it practical - the Rust compiler handles mundane things\n- Use git itself as reference implementation; run same tests against git where feasible\n- Never use `.unwrap()` in production code, avoid it in tests in favor of `.expect()` or `?`. Use `gix_testtools::Result` most of the time.\n- Use `.expect(\"why\")` with context explaining why expectations should hold, but only if it's relevant to the test.\n\n### Error Handling\n\n- Handle all errors, never `unwrap()`\n- Provide error chains making it easy to understand what went wrong\n- Binaries may use `anyhow::Error` exhaustively (user-facing errors)\n\n#### `gix-error` (preferred for plumbing crates)\n\nPlumbing crates are migrating from `thiserror` enums to `gix-error`. Check whether a crate already\nuses `gix-error` (look at its `Cargo.toml`); if it does, follow the patterns below. If it still uses\n`thiserror`, keep using `thiserror` for consistency within that crate.\n\n- **Error type alias**: `pub type Error = gix_error::Exn<gix_error::Message>;`\n- **Static messages**: `gix_error::message(\"something failed\")`\n- **Formatted messages**: `gix_error::message!(\"failed to read {path}\")`\n- **Wrapping callee errors with context**: `.or_raise(|| message(\"context about what failed\"))?`\n- **Standalone error (no callee)**: `Err(message(\"something went wrong\").raise())`\n- **Wrapping an `impl Error` with context**: `err.and_raise(message(\"context\"))`\n- **Closure/callback bounds**: use `Result<T, Exn>` (bare), not `Exn<Message>`;\n  inside the function, convert with `.or_raise(|| message(\"...\"))?`;\n  inside the closure, convert typed to bare with `.or_erased()`\n- **`Exn<E>` does NOT implement `std::error::Error`** — this is by design.\n  - To convert: use `.into_error()` to get `gix_error::Error` (which does implement `std::error::Error`)\n  - Example: `std::io::Error::other(exn.into_error())`\n- **In tests** returning `gix_testtools::Result` (= `Result<(), Box<dyn Error>>`), `Exn` can't be used\n  with `?` directly — use `.map_err(|e| e.into_error())?`\n- **Common imports**: `use gix_error::{message, ErrorExt, ResultExt};`\n- See `gix-error/src/lib.rs` module docs for a full migration guide from `thiserror`\n\n### Commit Messages\n\nFollow \"purposeful conventional commits\" style:\n\n- Use conventional commit prefixes ONLY if message should appear in changelog\n- Breaking changes MUST use suffix `!`: `change!:`, `remove!:`, `rename!:`\n- Features/fixes visible to users: `feat:`, `fix:`\n- Refactors/chores: no prefix (don't affect users)\n- Examples:\n  - `feat: add Repository::foo() to do great things. (#234)`\n  - `fix: don't panic when calling foo() in a bare repository. (#456)`\n  - `change!: rename Foo to Bar. (#123)`\n\n### Code Style\n\n- Follow existing patterns in the codebase\n- No `.unwrap()` - use `.expect(\"context\")` if you are sure this can't fail.\n- Prefer references in plumbing crates to avoid expensive clones\n- Avoid calling `.detach()` unless an owned value is explicitly required. Many `gix` APIs accept attached ids and references directly, so prefer keeping repository-backed handles like `gix::Id` when possible.\n- Use `gix_features::threading::*` for interior mutability primitives\n\n### Path Handling\n\n- Paths are byte-oriented in git (even on Windows via MSYS2 abstraction)\n- Use `gix::path::*` utilities to convert git paths (`BString`) to `OsStr`/`Path` or use custom types\n\n## Building and Testing\n\n### Quick Commands\n\n- `just test` - Run all tests, clippy, journey tests, and try building docs\n- `just check` - Build all code in suitable configurations\n- `just clippy` - Run clippy on all crates\n- `cargo test` - Run unit tests only\n\n### Build Variants\n\n- `cargo build --release` - Default build (big but pretty, ~2.5min)\n- `cargo build --release --no-default-features --features lean` - Lean build (~1.5min)\n- `cargo build --release --no-default-features --features small` - Minimal deps (~46s)\n\n### Test Best Practices\n\n- Run tests before making changes to understand existing issues\n- Use `GIX_TEST_IGNORE_ARCHIVES=1` when testing on macOS/Windows\n- Journey tests validate CLI behavior end-to-end\n- Fixture scripts should document what behavior they exercise and what makes\n  the fixture special. Leave clear-text breadcrumbs so future readers can tell\n  which details are essential to the test. Use markdown doc-strings when available.\n- Stabilize fixtures whose generated contents can vary by using the\n  `_needs_archive` variants of functions in `gix-testtools`; these always use\n  packaged archived fixtures instead of platform-local generated output.\n- Use assertion descriptions to state what is being asserted. For `assert*!`\n  macros this is the last parameter; for `insta::assert*` macros it is the\n  second parameter. Prefer messages that explain the invariant, not just that an\n  assertion failed.\n\n## Architecture Decisions\n\n### Plumbing vs Porcelain\n\n- **Plumbing crates**: Low-level, take references, expose mutable parts as arguments\n- **Porcelain (gix)**: High-level, convenient, may clone Repository for user convenience\n- Platforms: cheap to create, keep reference to Repository\n- Caches: more expensive, clone `Repository` or free of lifetimes\n\n### Options vs Context\n\n- Use `Options` for branching behavior configuration (can be defaulted)\n- Use `Context` for data required for operation (cannot be defaulted)\n\n## Crate Organization\n\n### Common Crates\n\n- `gix`: Main library entrypoint (porcelain)\n- `gix-object`, `gix-ref`, `gix-config`: Core git data structures\n- `gix-odb`, `gix-pack`: Object database and pack handling\n- `gix-diff`, `gix-merge`, `gix-status`: Operations\n- `gitoxide-core`: Shared CLI functionality\n\n## Documentation\n\n- High-level docs: README.md, CONTRIBUTING.md, DEVELOPMENT.md\n- Crate status: crate-status.md\n- Stability guide: STABILITY.md\n- Always update docs if directly related to code changes\n\n## CI and Releases\n\n- Ubuntu-latest git version is the compatibility target\n- `cargo smart-release` for releases (driven by commit messages)\n- Split breaking changes into separate commits per affected crate if one commit-message wouldn't be suitable for all changed crates.\n- First commit: breaking change only; second commit: adaptations\n\n## When Suggesting Changes\n\n1. Understand the plumbing vs porcelain distinction\n2. Check existing patterns in similar crates\n3. Follow error handling conventions strictly\n4. Ensure changes work with feature flags (small, lean, max, max-pure)\n5. Consider impact on both library and CLI users\n6. Test against real git repositories when possible\n"},"files":{"AGENTS.md":"# Copilot Instructions for Gitoxide\n\nThis repository contains `gitoxide` - a pure Rust implementation of Git. This document provides guidance for GitHub Copilot when working with this codebase.\n\n## Project Overview\n\n- **Language**: Rust (MSRV documented in gix/Cargo.toml)\n- **Structure**: Cargo workspace with multiple crates (gix-\\*, gitoxide-core, etc.)\n- **Main crates**: `gix` (library entrypoint), `gitoxide` binary (CLI tools: `gix` and `ein`)\n- **Purpose**: Provide a high-performance, safe Git implementation with both library and CLI interfaces\n\n## Development Practices\n\n### AI Agent Communication\n\n- AI agents communicating through a person's account must identify themselves, for example in issue or PR descriptions and comments.\n- AI assistance that does not replace the person as the speaker, such as proofreading or wording polish, does not require identification.\n- Attributing AI assistance in commit metadata, for example with an `Assisted-by:` or `Co-authored-by:` trailer, is welcome but not required.\n\n### Test-First Development\n\n- Protect against regression and make implementing features easy\n- Keep it practical - the Rust compiler handles mundane things\n- Use git itself as reference implementation; run same tests against git where feasible\n- Never use `.unwrap()` in production code, avoid it in tests in favor of `.expect()` or `?`. Use `gix_testtools::Result` most of the time.\n- Use `.expect(\"why\")` with context explaining why expectations should hold, but only if it's relevant to the test.\n\n### Error Handling\n\n- Handle all errors, never `unwrap()`\n- Provide error chains making it easy to understand what went wrong\n- Binaries may use `anyhow::Error` exhaustively (user-facing errors)\n\n#### `gix-error` (preferred for plumbing crates)\n\nPlumbing crates are migrating from `thiserror` enums to `gix-error`. Check whether a crate already\nuses `gix-error` (look at its `Cargo.toml`); if it does, follow the patterns below. If it still uses\n`thiserror`, keep using `thiserror` for consistency within that crate.\n\n- **Error type alias**: `pub type Error = gix_error::Exn<gix_error::Message>;`\n- **Static messages**: `gix_error::message(\"something failed\")`\n- **Formatted messages**: `gix_error::message!(\"failed to read {path}\")`\n- **Wrapping callee errors with context**: `.or_raise(|| message(\"context about what failed\"))?`\n- **Standalone error (no callee)**: `Err(message(\"something went wrong\").raise())`\n- **Wrapping an `impl Error` with context**: `err.and_raise(message(\"context\"))`\n- **Closure/callback bounds**: use `Result<T, Exn>` (bare), not `Exn<Message>`;\n  inside the function, convert with `.or_raise(|| message(\"...\"))?`;\n  inside the closure, convert typed to bare with `.or_erased()`\n- **`Exn<E>` does NOT implement `std::error::Error`** — this is by design.\n  - To convert: use `.into_error()` to get `gix_error::Error` (which does implement `std::error::Error`)\n  - Example: `std::io::Error::other(exn.into_error())`\n- **In tests** returning `gix_testtools::Result` (= `Result<(), Box<dyn Error>>`), `Exn` can't be used\n  with `?` directly — use `.map_err(|e| e.into_error())?`\n- **Common imports**: `use gix_error::{message, ErrorExt, ResultExt};`\n- See `gix-error/src/lib.rs` module docs for a full migration guide from `thiserror`\n\n### Commit Messages\n\nFollow \"purposeful conventional commits\" style:\n\n- Use conventional commit prefixes ONLY if message should appear in changelog\n- Breaking changes MUST use suffix `!`: `change!:`, `remove!:`, `rename!:`\n- Features/fixes visible to users: `feat:`, `fix:`\n- Refactors/chores: no prefix (don't affect users)\n- Examples:\n  - `feat: add Repository::foo() to do great things. (#234)`\n  - `fix: don't panic when calling foo() in a bare repository. (#456)`\n  - `change!: rename Foo to Bar. (#123)`\n\n### Code Style\n\n- Follow existing patterns in the codebase\n- No `.unwrap()` - use `.expect(\"context\")` if you are sure this can't fail.\n- Prefer references in plumbing crates to avoid expensive clones\n- Avoid calling `.detach()` unless an owned value is explicitly required. Many `gix` APIs accept attached ids and references directly, so prefer keeping repository-backed handles like `gix::Id` when possible.\n- Use `gix_features::threading::*` for interior mutability primitives\n\n### Path Handling\n\n- Paths are byte-oriented in git (even on Windows via MSYS2 abstraction)\n- Use `gix::path::*` utilities to convert git paths (`BString`) to `OsStr`/`Path` or use custom types\n\n## Building and Testing\n\n### Quick Commands\n\n- `just test` - Run all tests, clippy, journey tests, and try building docs\n- `just check` - Build all code in suitable configurations\n- `just clippy` - Run clippy on all crates\n- `cargo test` - Run unit tests only\n\n### Build Variants\n\n- `cargo build --release` - Default build (big but pretty, ~2.5min)\n- `cargo build --release --no-default-features --features lean` - Lean build (~1.5min)\n- `cargo build --release --no-default-features --features small` - Minimal deps (~46s)\n\n### Test Best Practices\n\n- Run tests before making changes to understand existing issues\n- Use `GIX_TEST_IGNORE_ARCHIVES=1` when testing on macOS/Windows\n- Journey tests validate CLI behavior end-to-end\n- Fixture scripts should document what behavior they exercise and what makes\n  the fixture special. Leave clear-text breadcrumbs so future readers can tell\n  which details are essential to the test. Use markdown doc-strings when available.\n- Stabilize fixtures whose generated contents can vary by using the\n  `_needs_archive` variants of functions in `gix-testtools`; these always use\n  packaged archived fixtures instead of platform-local generated output.\n- Use assertion descriptions to state what is being asserted. For `assert*!`\n  macros this is the last parameter; for `insta::assert*` macros it is the\n  second parameter. Prefer messages that explain the invariant, not just that an\n  assertion failed.\n\n## Architecture Decisions\n\n### Plumbing vs Porcelain\n\n- **Plumbing crates**: Low-level, take references, expose mutable parts as arguments\n- **Porcelain (gix)**: High-level, convenient, may clone Repository for user convenience\n- Platforms: cheap to create, keep reference to Repository\n- Caches: more expensive, clone `Repository` or free of lifetimes\n\n### Options vs Context\n\n- Use `Options` for branching behavior configuration (can be defaulted)\n- Use `Context` for data required for operation (cannot be defaulted)\n\n## Crate Organization\n\n### Common Crates\n\n- `gix`: Main library entrypoint (porcelain)\n- `gix-object`, `gix-ref`, `gix-config`: Core git data structures\n- `gix-odb`, `gix-pack`: Object database and pack handling\n- `gix-diff`, `gix-merge`, `gix-status`: Operations\n- `gitoxide-core`: Shared CLI functionality\n\n## Documentation\n\n- High-level docs: README.md, CONTRIBUTING.md, DEVELOPMENT.md\n- Crate status: crate-status.md\n- Stability guide: STABILITY.md\n- Always update docs if directly related to code changes\n\n## CI and Releases\n\n- Ubuntu-latest git version is the compatibility target\n- `cargo smart-release` for releases (driven by commit messages)\n- Split breaking changes into separate commits per affected crate if one commit-message wouldn't be suitable for all changed crates.\n- First commit: breaking change only; second commit: adaptations\n\n## When Suggesting Changes\n\n1. Understand the plumbing vs porcelain distinction\n2. Check existing patterns in similar crates\n3. Follow error handling conventions strictly\n4. Ensure changes work with feature flags (small, lean, max, max-pure)\n5. Consider impact on both library and CLI users\n6. Test against real git repositories when possible\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Copilot Instructions for Gitoxide\n\nThis repository contains `gitoxide` - a pure Rust implementation of Git. This document provides guidance for GitHub Copilot when working with this codebase.\n\n## Project Overview\n\n- **Language**: Rust (MSRV documented in gix/Cargo.toml)\n- **Structure**: Cargo workspace with multiple crates (gix-\\*, gitoxide-core, etc.)\n- **Main crates**: `gix` (library entrypoint), `gitoxide` binary (CLI tools: `gix` and `ein`)\n- **Purpose**: Provide a high-performance, safe Git implementation with both library and CLI interfaces\n\n## Development Practices\n\n### AI Agent Communication\n\n- AI agents communicating through a person's account must identify themselves, for example in issue or PR descriptions and comments.\n- AI assistance that does not replace the person as the speaker, such as proofreading or wording polish, does not require identification.\n- Attributing AI assistance in commit metadata, for example with an `Assisted-by:` or `Co-authored-by:` trailer, is welcome but not required.\n\n### Test-First Development\n\n- Protect against regression and make implementing features easy\n- Keep it practical - the Rust compiler handles mundane things\n- Use git itself as reference implementation; run same tests against git where feasible\n- Never use `.unwrap()` in production code, avoid it in tests in favor of `.expect()` or `?`. Use `gix_testtools::Result` most of the time.\n- Use `.expect(\"why\")` with context explaining why expectations should hold, but only if it's relevant to the test.\n\n### Error Handling\n\n- Handle all errors, never `unwrap()`\n- Provide error chains making it easy to understand what went wrong\n- Binaries may use `anyhow::Error` exhaustively (user-facing errors)\n\n#### `gix-error` (preferred for plumbing crates)\n\nPlumbing crates are migrating from `thiserror` enums to `gix-error`. Check whether a crate already\nuses `gix-error` (look at its `Cargo.toml`); if it does, follow the patterns below. If it still uses\n`thiserror`, keep using `thiserror` for consistency within that crate.\n\n- **Error type alias**: `pub type Error = gix_error::Exn<gix_error::Message>;`\n- **Static messages**: `gix_error::message(\"something failed\")`\n- **Formatted messages**: `gix_error::message!(\"failed to read {path}\")`\n- **Wrapping callee errors with context**: `.or_raise(|| message(\"context about what failed\"))?`\n- **Standalone error (no callee)**: `Err(message(\"something went wrong\").raise())`\n- **Wrapping an `impl Error` with context**: `err.and_raise(message(\"context\"))`\n- **Closure/callback bounds**: use `Result<T, Exn>` (bare), not `Exn<Message>`;\n  inside the function, convert with `.or_raise(|| message(\"...\"))?`;\n  inside the closure, convert typed to bare with `.or_erased()`\n- **`Exn<E>` does NOT implement `std::error::Error`** — this is by design.\n  - To convert: use `.into_error()` to get `gix_error::Error` (which does implement `std::error::Error`)\n  - Example: `std::io::Error::other(exn.into_error())`\n- **In tests** returning `gix_testtools::Result` (= `Result<(), Box<dyn Error>>`), `Exn` can't be used\n  with `?` directly — use `.map_err(|e| e.into_error())?`\n- **Common imports**: `use gix_error::{message, ErrorExt, ResultExt};`\n- See `gix-error/src/lib.rs` module docs for a full migration guide from `thiserror`\n\n### Commit Messages\n\nFollow \"purposeful conventional commits\" style:\n\n- Use conventional commit prefixes ONLY if message should appear in changelog\n- Breaking changes MUST use suffix `!`: `change!:`, `remove!:`, `rename!:`\n- Features/fixes visible to users: `feat:`, `fix:`\n- Refactors/chores: no prefix (don't affect users)\n- Examples:\n  - `feat: add Repository::foo() to do great things. (#234)`\n  - `fix: don't panic when calling foo() in a bare repository. (#456)`\n  - `change!: rename Foo to Bar. (#123)`\n\n### Code Style\n\n- Follow existing patterns in the codebase\n- No `.unwrap()` - use `.expect(\"context\")` if you are sure this can't fail.\n- Prefer references in plumbing crates to avoid expensive clones\n- Avoid calling `.detach()` unless an owned value is explicitly required. Many `gix` APIs accept attached ids and references directly, so prefer keeping repository-backed handles like `gix::Id` when possible.\n- Use `gix_features::threading::*` for interior mutability primitives\n\n### Path Handling\n\n- Paths are byte-oriented in git (even on Windows via MSYS2 abstraction)\n- Use `gix::path::*` utilities to convert git paths (`BString`) to `OsStr`/`Path` or use custom types\n\n## Building and Testing\n\n### Quick Commands\n\n- `just test` - Run all tests, clippy, journey tests, and try building docs\n- `just check` - Build all code in suitable configurations\n- `just clippy` - Run clippy on all crates\n- `cargo test` - Run unit tests only\n\n### Build Variants\n\n- `cargo build --release` - Default build (big but pretty, ~2.5min)\n- `cargo build --release --no-default-features --features lean` - Lean build (~1.5min)\n- `cargo build --release --no-default-features --features small` - Minimal deps (~46s)\n\n### Test Best Practices\n\n- Run tests before making changes to understand existing issues\n- Use `GIX_TEST_IGNORE_ARCHIVES=1` when testing on macOS/Windows\n- Journey tests validate CLI behavior end-to-end\n- Fixture scripts should document what behavior they exercise and what makes\n  the fixture special. Leave clear-text breadcrumbs so future readers can tell\n  which details are essential to the test. Use markdown doc-strings when available.\n- Stabilize fixtures whose generated contents can vary by using the\n  `_needs_archive` variants of functions in `gix-testtools`; these always use\n  packaged archived fixtures instead of platform-local generated output.\n- Use assertion descriptions to state what is being asserted. For `assert*!`\n  macros this is the last parameter; for `insta::assert*` macros it is the\n  second parameter. Prefer messages that explain the invariant, not just that an\n  assertion failed.\n\n## Architecture Decisions\n\n### Plumbing vs Porcelain\n\n- **Plumbing crates**: Low-level, take references, expose mutable parts as arguments\n- **Porcelain (gix)**: High-level, convenient, may clone Repository for user convenience\n- Platforms: cheap to create, keep reference to Repository\n- Caches: more expensive, clone `Repository` or free of lifetimes\n\n### Options vs Context\n\n- Use `Options` for branching behavior configuration (can be defaulted)\n- Use `Context` for data required for operation (cannot be defaulted)\n\n## Crate Organization\n\n### Common Crates\n\n- `gix`: Main library entrypoint (porcelain)\n- `gix-object`, `gix-ref`, `gix-config`: Core git data structures\n- `gix-odb`, `gix-pack`: Object database and pack handling\n- `gix-diff`, `gix-merge`, `gix-status`: Operations\n- `gitoxide-core`: Shared CLI functionality\n\n## Documentation\n\n- High-level docs: README.md, CONTRIBUTING.md, DEVELOPMENT.md\n- Crate status: crate-status.md\n- Stability guide: STABILITY.md\n- Always update docs if directly related to code changes\n\n## CI and Releases\n\n- Ubuntu-latest git version is the compatibility target\n- `cargo smart-release` for releases (driven by commit messages)\n- Split breaking changes into separate commits per affected crate if one commit-message wouldn't be suitable for all changed crates.\n- First commit: breaking change only; second commit: adaptations\n\n## When Suggesting Changes\n\n1. Understand the plumbing vs porcelain distinction\n2. Check existing patterns in similar crates\n3. Follow error handling conventions strictly\n4. Ensure changes work with feature flags (small, lean, max, max-pure)\n5. Consider impact on both library and CLI users\n6. Test against real git repositories when possible\n","category":"root","tokens":1907}]}