### Install GitPython from Source

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/gix-pack/tests/fixtures/objects/f139391424a8c623adadf2388caec73e5e90865b.txt

Instructions to install GitPython by running the setup script from the downloaded source code.

```Python
python setup.py install
```

--------------------------------

### Install Gitoxide from Source (Default Max Features)

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/README.md

This command installs `gitoxide` from source using Cargo with its default `max` features. This is generally the fastest installation method but requires `cmake` to be present on the system for successful compilation. Users should ensure `cmake` is installed according to their platform's requirements.

```sh
cargo install gitoxide
```

--------------------------------

### Install Gitoxide on Arch Linux

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/README.md

This command installs the `gitoxide` tool from the official Arch Linux `community` repository. It leverages `pacman`, the Arch Linux package manager, to fetch and install the pre-built binary.

```sh
pacman -S gitoxide
```

--------------------------------

### Install Gitoxide from Source (Lean Features)

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/README.md

This command installs `gitoxide` from source using Cargo with the `lean` feature set. This configuration results in smaller binaries and faster build times by trading off some CLI implementation features. It's suitable for environments where binary size and build speed are prioritized.

```sh
cargo install gitoxide --locked --no-default-features --features lean
```

--------------------------------

### Install Gitoxide on Exherbo Linux

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/README.md

These commands install `gitoxide` on Exherbo Linux using the `cave` package manager. The first command resolves the Rust repository, and the second installs the `gitoxide` package, ensuring all necessary dependencies are met from the specified repository.

```sh
cave resolve -x repository/rust
cave resolve -x gitoxide
```

--------------------------------

### Install Gitoxide from Source (Max Pure Features)

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/README.md

This command installs `gitoxide` from source using Cargo, specifically enabling the `max-pure` features. This configuration avoids external C toolchain dependencies, making it more compatible across various platforms, and is recommended if SSL certificate issues arise during clones.

```sh
cargo install gitoxide --locked --no-default-features --features max-pure
```

--------------------------------

### Install Latest Gitoxide Release from Git Repository

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/README.md

This command installs the latest unpublished `max` release of `gitoxide` directly from its Git repository. It's useful for developers who want to use the absolute latest version of the tool, bypassing published crates.io releases.

```sh
cargo install --git https://github.com/GitoxideLabs/gitoxide gitoxide
```

--------------------------------

### Install GitPython using easy_install

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/gix-pack/tests/fixtures/objects/f139391424a8c623adadf2388caec73e5e90865b.txt

Instructions to easily obtain and install GitPython using the easy_install tool.

```Python
easy_install gitpython
```

--------------------------------

### Conventional Commit Message Examples (Features and Fixes)

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/DEVELOPMENT.md

Examples of commit messages for new features ('feat:') or bug fixes ('fix:'). These changes are visible to users and are included in the changelog, guiding minor or patch version bumps.

```Conventional Commit
feat: add `Repository::foo()` to do great things. (#234)

And here is how it's used and some more details.
```

```Conventional Commit
fix: don't panic when calling `foo()` in a bare repository. (#456)
```

--------------------------------

### Build Gitoxide Docker Image

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/README.md

This command builds a Docker image named `gitoxide:latest` from the `etc/docker/Dockerfile.alpine` Dockerfile, compressing the build context. This image contains the compiled `gitoxide` binaries, ready for use in subsequent Docker stages.

```sh
docker build -f etc/docker/Dockerfile.alpine -t gitoxide:latest --compress .
```

--------------------------------

### API Design: `Options` vs `Context` Parameters

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/DEVELOPMENT.md

Distinguishes between `Options` for configurable branching behavior (defaultable) and `Context` for required operational data (non-defaultable), using `gix_config::path::Context` as an example.

```Rust Guidelines
- Use `Options` whenever there is something to configure in terms of branching behaviour. It can be defaulted, and if it can't these fields should be parameters of the method
  that takes these `Options`.
- Use `Context` when data is required to perform an operation at all. See `gix_config::path::Context` as reference. It can't be defaulted and the fields could also be parameters.
```

--------------------------------

### Integrate Gitoxide Binaries into Docker Image

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/README.md

These Dockerfile commands copy the `gix` and `ein` binaries from a previously built `gitoxide:latest` image into the current image's `/usr/local/bin/` directory. It then demonstrates how to use the copied `gix` binary to clone a Git repository, showcasing its direct replacement for standard `git` commands within a Docker environment.

```dockerfile
COPY --from gitoxide:latest /bin/gix /usr/local/bin/
COPY --from gitoxide:latest /bin/ein /usr/local/bin/

RUN /usr/local/bin/gix clone --depth 1 https://github.com/GitoxideLabs/gitoxide gitoxide
```

--------------------------------

### Install Perl on Fedora for OpenSSL Build

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/README.md

This command installs `perl` on Fedora systems using `dnf`. It addresses a known build failure where `OpenSSL` requires `perl` to build properly, particularly when compiling `gitoxide` from source. This is a dependency for certain `gitoxide` feature configurations.

```sh
dnf install perl
```

--------------------------------

### Build Gitoxide Docker Image (Alpine Base)

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/README.md

This command builds a Docker image for `gitoxide` using the specified `Dockerfile.alpine`. The image is tagged `gitoxide:latest` and targets the `pipeline` stage, compressing the build context. This is useful for CI/CD pipelines that require a `gitoxide` environment, as no official image is currently provided.

```sh
docker build -f etc/docker/Dockerfile.alpine -t gitoxide:latest --compress . --target=pipeline
```

--------------------------------

### Lifetime Management in Gitoxide Crates

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/DEVELOPMENT.md

Guidelines for lifetime management, preferring references in plumbing crates to avoid clones, and discussing `Platforms` in porcelain crates which should reference `Repository` instances or clone `Repository` for expensive structures.

```Rust Guidelines
In _plumbing_ crates, prefer to default to keeping references if this is feasible to avoid typically expensive clones.

In _porcelain_ crates, like `gix`, we have `Platforms` which are typically cheap enough to create on demand as they configure one or more method calls. These
should keep a reference to the `Repository` instance that created them as the user is expected to clone the `Repository` if there is the need.
However, if these structures are more expensive, call them `Cache` or `<NotPlatform>` and prefer to clone the `Repository` into them or otherwise keep them free of lifetimes
to allow the user to keep this structure around for repeated calls. References for this paragraph are [this PR](https://github.com/Canop/bacon/pull/98) and
[this discussion](https://github.com/GitoxideLabs/gitoxide/discussions/675).
```

--------------------------------

### SHA-256 Support Checklist for Gitoxide

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/DEVELOPMENT.md

A checklist of items required for eventual SHA-256 support in Gitoxide, including handling `gpgsig-sha256`, index V3, and Pack file PSRC field.

```Gitoxide Development Notes
* read `hash-function-transition.txt`
* [x] support `gpgsig-sha256` field - we won't break, but also don't do anything with it (e.g. `extra_headers`)
* [ ] support index V3
* [ ] Pack file PSRC field
```

--------------------------------

### Git Plumbing vs. Porcelain Commands Definition

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/DEVELOPMENT.md

Defines Git's plumbing (lower-level, rarely used) and porcelain (user-friendly) commands, noting that both must self-document via `--help`.

```Git Concepts
Both terms are coming from the `git` implementation itself, even though it won't necessarily point out which commands are plumbing and which
are porcelain.
The term *plumbing* refers to lower-level, more rarely used commands that complement porcelain by being invoked by it or by hand for certain use
cases.
The term *porcelain* refers to those with a decent user experience, they are primarily intended for use by humans.

In any case, both types of programs must self-document their capabilities using through the `--help` flag.
```

--------------------------------

### Gitattributes File Configuration Examples

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/gix-attributes/tests/fixtures/attributes/various.txt

Illustrates various patterns and attribute assignments used in a .gitattributes file, including comments, quoted patterns, and escaped characters.

```Gitattributes
# no attribute for now
*.[oa] c

# comment
"*.html" a    b=c

# other comment  
\!foo.html x

\#a/path -a
/* !b
```

--------------------------------

### Install cargo-fuzz for project fuzzing

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/gix-refspec/README.md

Installs the `cargo-fuzz` tool, which is necessary for performing fuzz testing on the `gix-refspec` project. This command adds the `cargo-fuzz` executable to your Cargo bin directory.

```Shell
cargo install cargo-fuzz
```

--------------------------------

### Conventional Commit Message Examples (Breaking Changes)

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/DEVELOPMENT.md

Examples of commit messages for breaking changes, using the 'change!' or 'remove!' prefixes. These messages must appear in the changelog and are used by `cargo smart-release` to trigger major version bumps.

```Conventional Commit
change!: rename `Foo` to `Bar`. (#123)

And this is why we do it in the body.
```

```Conventional Commit
remove!: `Repository::obsolete()`.

Nobody used this method.
```

--------------------------------

### Git Pathspec Command Line Examples

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/reports/23-08.md

Illustrates common ways to use pathspecs with Git commands, differentiating between shell and Git's internal expansion. It also shows an example of a complex pathspec with attributes.

```Shell
git add *.rs
```

```Shell
git add '*.rs'
```

```APIDOC
Complex Pathspec Syntax Example:
:(attr:export-ignore,icase,glob,exclude)glory
```

--------------------------------

### Git Path Encoding Considerations

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/DEVELOPMENT.md

Explains Git's byte-oriented path encoding, even on Windows (assuming MSYS2 abstraction), and the use of `os_str_bytes` for conversion to `OsStr` in Rust, acknowledging potential encoding variations.

```Rust Guidelines
- For `git`, paths are just bytes no matter on which platform. We assume that on windows its path handling goes through some abstraction layer like `MSYS2`
    which avoids it to seeing UTF-16 encoded paths (and writing them). Thus it should be safe to assume `git`s path encoding is byte oriented.
  - Assuming UTF8-ish bytes in paths produced by `git` even on windows due to `MSYS2`, we use `os_str_bytes` to convert these back into `OsStr` and derivatives like `Path`
    as needed even though it might not always be the case depending on the actual encoding used by `MSYS2` or other abstraction layers, or avoiding to use std types altogether
    using our own instead.
```

--------------------------------

### Shared Ownership with `gix_features::threading::OwnShared`

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/DEVELOPMENT.md

Recommends `gix_features::threading::OwnShared` for shared resources used by thread-local handles, noting its minimal performance overhead compared to shared references.

```Rust Guidelines
Use `gix_features::threading::OwnShared` particularly when shared resources supposed to be used by thread-local handles. Going through a wrapper for shared ownership is fast
    and won't be the bottleneck, as it's only about 16% slower than going through a shared reference on a single core.
```

--------------------------------

### Conventional Commit Message Examples

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/reports/21-10.md

Examples of conventional commit messages that `cargo smart-release` parses to derive appropriate version bumps and `cargo changelog` uses for generating changelogs. These messages indicate new features or breaking changes.

```Text
feat: to indicate a new feature
```

```Text
change!: a breaking change
```

--------------------------------

### Fuzzing `gix-pathspec` with `cargo fuzz`

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/gix-pathspec/README.md

Instructions for installing `cargo-fuzz` and executing fuzzing targets for the `gix-pathspec` crate. This involves listing available targets and running specific ones using `cargo +nightly`.

```Shell
cargo install cargo-fuzz
```

```Shell
cargo fuzz list
```

```Shell
cargo +nightly fuzz run <target>
```

--------------------------------

### Publishing All Gitoxide Crates

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/DEVELOPMENT.md

Executes the `make publish-all` command to publish all Gitoxide crates in leaf-first order. This process relies on `cargo release` and requires prior execution of `cargo release minor|major` (aborted during verification) to update dependent versions for API-breaking changes.

```sh
make publish-all
```

--------------------------------

### Git Porcelain CLI Behavior Rules

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/DEVELOPMENT.md

Rules for porcelain CLI commands: default stderr output for progress (only when needed), localtime timestamps, and non-progress info to stdout.

```Git Concepts
* Provides output to stderr by default to provide progress information. There is no need to allow disabling it, but it shouldn't show up unless
  the operation takes some time.
* If timestamps are shown, they are in localtime.
* Non-progress information goes to stdout.
```

--------------------------------

### Error Handling: `unwrap()` vs `expect()` in Rust

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/DEVELOPMENT.md

Guidance on Rust error handling, advising against `unwrap()` in favor of `quick_error!()` or `Box<dyn std::error::Error>`, and recommending `expect()` for assertions on `Options` with contextual explanations.

```Rust Guidelines
* don't use unwrap, not even in tests. Instead use `quick_error!()` or `Box<dyn std::error::Error>`.
* Use `expect(…)` as assertion on Options, providing context on *why* the expectations should hold. Or in other words,
  answer "This should work _because_…<expect(…)>"
```

--------------------------------

### Enabling Extensive Git Debug Tracing

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/DEVELOPMENT.md

Shows how to set various `GIT_TRACE` environment variables, `GIT_CURL_VERBOSE`, and `GIT_SSH_COMMAND` to enable maximum debugging output for Git commands, useful for deep troubleshooting. Includes options for `GIT_TRACE2_PERF` for performance statistics.

```sh
GIT_TRACE=true \
GIT_TRACE_PACK_ACCESS=true \
GIT_TRACE_PACKET=true \
GIT_TRACE_PACKFILE=true \
GIT_TRACE_PERFORMANCE=true \
GIT_TRACE_SHALLOW=true \
GIT_TRACE_SETUP=true \
GIT_CURL_VERBOSE=true \
GIT_SSH_COMMAND=\"ssh -VVV\" \
git <command>

# Optional: Add for statistics and variables
GIT_TRACE2_PERF=1
GIT_TRACE2_PERF_BRIEF=1
```

--------------------------------

### Git Plumbing CLI Behavior Rules

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/DEVELOPMENT.md

Rules for plumbing CLI commands: no default progress/logging, UTC timestamps if logging enabled, and no requirement for a Git repository, taking all info via command-line.

```Git Concepts
* does not show any progress or logging output by default
* if supported and logging is enabled, it will show timestamps in UTC
* it does not need a git repository, but instead takes all required information via the command-line
```

--------------------------------

### Fuzzing `gix-revision` with `cargo fuzz`

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/gix-revision/README.md

Provides commands for installing `cargo-fuzz` and running fuzzing targets for the `gix-revision` project, including listing available targets.

```Shell
cargo install cargo-fuzz
```

```Shell
cargo fuzz list
cargo +nightly fuzz run <target>
```

--------------------------------

### Convert GitHub Repository Metadata to JSONL

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/corpus/README.md

Converts the downloaded `repo_metadata.json` file, obtained from Kaggle, into a JSONL (JSON Lines) format. This conversion is a prerequisite for processing the metadata for corpus generation.

```shell
json-to-jsonl.sh repo_metadata.json
```

--------------------------------

### Concurrency Primitives and Interior Mutability in Gitoxide

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/DEVELOPMENT.md

Guidelines for using `gix_features::threading` primitives for interior mutability, emphasizing upgradable readers for minimal contention and the `Sync` requirement for non-thread-local types when parallelism is enabled.

```Rust Guidelines
- When using primitives to support interior mutability, use the provided ones and utility functions in `gix_features::threading::*` exclusively to allow switching between
    thread-safe and none-threadsafe versions at compile time.
      - The preferred way of using it is to start out as upgradable reader, and upgrading to write if needed, keeping contention to a minimum.
  - If _shared ownership_ is involved, one always needs _interior mutability_, but may still decide to use an API that requires `&mut self` if locally stored caches are involved.
  - Types that are not thread-local must be `Sync`, but only if the `gix-features/parallel` is enabled due to the usage of `gix_features::threading::…` primitives which won't
    be thread-safe without the feature.
```

--------------------------------

### Clone a Subset of Repositories from JSONL

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/corpus/README.md

Clones a specified number of repositories from a `repo_metadata.jsonl` file into the designated corpus location. This command uses `head` to select the desired number of entries from the metadata file for cloning.

```shell
head -n 999 repo_metadata.sample.jsonl | ./clone-repos.sh <corpus>
```

--------------------------------

### gix corpus Sub-command API Documentation

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/corpus/README.md

Documentation for the `gix corpus` sub-command, which is designed to run specifically implemented commands against the repository corpus in a parallel fashion. The results of these operations are stored in a local SQLite database for subsequent comparison and analysis.

```APIDOC
gix corpus:
  description: Runs specifically implemented commands against the corpus in a parallel fashion.
  output: Results are stored in a local sqlite database for later comparison.
```

--------------------------------

### Perform Post-Cloning Operations for Specific Repositories

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/corpus/README.md

After manually cloning specific large or complex repositories, this script navigates into the corpus directory. It then executes `git read-tree @` and `git commit-graph write --no-progress --reachable` for each specified repository to optimize them for `gitoxide`'s analysis.

```shell
cd <corpus>
for d in github.com/archlinux/svntogit-community.git github.com/NagatoDEV/PlayStation-Home-Master-Archive.git github.com/fz139/vigruzki.git; do
    git -C $d read-tree @
    git -C $d commit-graph write --no-progress --reachable
done
```

--------------------------------

### Generating and Truncating Git Object Fixtures

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/DEVELOPMENT.md

Provides shell commands to generate Git object data fixtures using `git cat-file --batch` and then remove the trailing newline byte using `truncate` for proper formatting, as required for Gitoxide fixtures.

```sh
echo c56a8e7aa92c86c41a923bc760d2dc39e8a31cf7  | git cat-file --batch | tail +2 > fixture
truncate -s -1 fixture
```

--------------------------------

### Common Gitignore Patterns for File and Directory Exclusion

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/gix-ignore/tests/fixtures/ignore/various.txt

This snippet demonstrates how to configure a .gitignore file to ignore specific file extensions (like .o and .a), ignore all HTML files while creating an exception for a manually maintained file (foo.html), and exclude everything except a specific subdirectory (foo/bar).

```Gitignore
# ignore objects and archives, anywhere in the tree.
*.[oa]

# ignore generated html files,
*.html

# except foo.html which is maintained by hand
!foo.html

# exclude everything except directory foo/bar
/*
!/foo
/foo/*
!/foo/bar
```

--------------------------------

### Run a specific fuzzing target

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/gix-refspec/README.md

Executes a chosen fuzzing target using the nightly Rust toolchain. Replace `<target>` with the name of the specific fuzzing target you wish to run, for example, `parse`.

```Shell
cargo +nightly fuzz run <target>
```

--------------------------------

### Calculate Repositories Fitting Available Disk Space in Python

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/corpus/README.md

A Python snippet designed for a Jupyter Notebook to filter and analyze GitHub repository metadata. It sorts repositories by stars, excludes those larger than 5GB, and calculates how many repositories can fit within a user-defined disk space limit (e.g., 3.5TB).

```python
five_gb_in_kb = 5 * 1024 * 1024
limit = 3500 * 1024 * 1024

# Order by 'stars' column and filter by 'diskUsageKb'
df = df[df['diskUsageKb'] < five_gb_in_kb]
df_sorted = df.sort_values(by='stars', ascending=False)

# Calculate how many entries would fit into 350GB
disk_usage_cumsum = df_sorted['diskUsageKb'].cumsum()
(disk_usage_cumsum <= limit).sum()
```

--------------------------------

### Manually Clone Large Repository: fz139/vigruzki

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/corpus/README.md

Clones a specific bare Git repository, `fz139/vigruzki`, characterized by 100MB+ files with numerous append-only changes. This repository is included to trigger worst-case delta-tree behavior, helping identify and mitigate performance issues in `gitoxide`.

```shell
git clone --bare https://github.com/fz139/vigruzki <corpus>/github.com/fz139/vigruzki.git
```

--------------------------------

### Manually Clone Large Repository: archlinux/svntogit-community

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/corpus/README.md

Clones a specific bare Git repository, `archlinux/svntogit-community`, which contains over 1.3 million commits. This repository is added to the corpus to evaluate `gitoxide`'s performance and stability when processing repositories with exceptionally long commit histories.

```shell
git clone --bare https://github.com/archlinux/svntogit-community <corpus>/github.com/archlinux/svntogit-community.git
```

--------------------------------

### Manually Clone Large Repository: PlayStation-Home-Master-Archive

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/corpus/README.md

Clones a specific large bare Git repository known for its extensive tree and binary data. This repository, `PlayStation-Home-Master-Archive`, is included in the corpus to test `gitoxide`'s handling of huge binary files within massive directory structures.

```shell
git clone --bare https://github.com/NagatoDEV/PlayStation-Home-Master-Archive  <corpus>/github.com/NagatoDEV/PlayStation-Home-Master-Archive.git
```

--------------------------------

### Run Ad-Hoc `gix` Commands Across Corpus

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/corpus/README.md

Executes a specified `gix` command against all available repositories within the corpus. This command uses `ein t find` to locate repositories and `xargs` to run the `gix` command in parallel, which is useful for testing new functionalities or commands.

```shell
ein t find <corpus> | xargs -P10 -I {} bash -c 'echo {}; gix -r {} <command>'
```

--------------------------------

### Gitoxide File Inclusion and Exclusion Patterns

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/gix-ignore/tests/fixtures/ignore/precious.txt

Demonstrates various pattern types used in Gitoxide for specifying which files are considered 'precious' (not discarded) or excluded. Patterns can start with `$` to mark files as precious, use `*` as a wildcard, and `!` to negate a pattern. Comments are indicated by `#`.

```Gitoxide Pattern Syntax
$.config
\$starts-with-dollar
# html files are now precious and won't be discarded
$*.html

!foo.html

# this isn't allowed and ignored
!$foo.html

# but this is a literal !/* that is precious
$!/*
```

--------------------------------

### Git Commit Metadata Example

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/gix-object/tests/fixtures/commit/invalid-actor.txt

This snippet displays the raw metadata of a Git commit, including the tree hash, parent commit hash, author information (name, email, timestamp), committer information, and the commit message. This format is typical of `git cat-file -p <commit-hash>` output.

```Git Log
tree 220738fd4199e95a2b244465168366a73ebdf271
parent 209fbe2d632761b30b7b17422914e11b93692833
author Gregor Hartmann<gh <Gregor Hartmann<gh@openoffice.org>> 1282910542 +0200
committer Gregor Hartmann<gh <Gregor Hartmann<gh@openoffice.org>> 1282910542 +0200

build breakers
```

--------------------------------

### Non-Conventional Commit Message Examples (Internal Changes)

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/DEVELOPMENT.md

Examples of commit messages for internal changes like refactors or chores that do not affect the public API. These messages do not use conventional prefixes and are not intended for the changelog, as users of the API generally do not care about them.

```Commit Message
make test module structure similar to the modules they are testing for consistency
```

```Commit Message
`make fmt`
```

```Commit Message
thanks clippy
```

--------------------------------

### Enhancing codevis for Code Visualization

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/reports/22-09.md

Describes the process of enhancing the codevis tool, originally a pre-configured program, by integrating clap for command-line arguments and prodash for progress indication. It also mentions adding multi-threading and optimizations for memory-constrained systems.

```Rust
Integrate `clap` for CLI arguments.
Integrate `prodash` for progress display.
Implement multi-threading.
Apply various optimizations for memory efficiency.
```

--------------------------------

### gix-credentials Crate Helper Integration

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/crate-status.md

The `gix-credentials` crate facilitates launching Git credential helpers. It supports built-in `git credential` programs, scripts, absolute paths, and program names transformed into `git credential-<name>`. It also provides `helper::main()` for custom Rust helpers.

```APIDOC
### gix-credentials
* [x] launch git credentials helpers with a given action
  - [x] built-in `git credential` program
  - [x] as scripts
  - [x] as absolute paths to programs with optional arguments
  - [x] program name with optional arguments, transformed into `git credential-<name>`
* [x] `helper::main()` for easy custom credential helper programs written in Rust
```

--------------------------------

### Example of Overwriting Email Values in Custom Format

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/gix-mailmap/tests/fixtures/overwrite.txt

This snippet demonstrates a pattern for overwriting values, specifically email addresses, associated with different identifiers. Each line shows an identifier followed by one or more email addresses, with 'overwritten' variants indicating the updated state. This format suggests a system for tracking and updating user or commit-related email information.

```Custom Format
A <old-a-email>
A-overwritten <old-a-email>

B <new-b-email> <old-b-email>
B-overwritten <new-b-email-overwritten> <old-b-email>

C <new-c-email> old-C <old-c-email>
C-overwritten <new-c-email-overwritten> old-C <old-c-email>

<new-d-email> <old-d-email>
<new-d-email-overwritten> <old-d-email>
```

--------------------------------

### gix Repository Initialization

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/crate-status.md

Functionality for initializing Git repositories, ensuring proper configuration based on the platform (e.g., ignorecase, filemode).

```APIDOC
initialize:
  - Proper configuration depending on platform (e.g. ignorecase, filemode, …)
```

--------------------------------

### Compare Git Repository Cloning: git2 vs. Gitoxide

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/speak/gitmerge-2024.marp.md

This section provides a direct comparison between cloning a Git repository using the `git2` library and the concise `gix` implementation. It highlights the differences in API design and verbosity for a common Git operation.

```Rust
#[tauri::command(async)]
pub fn git_clone_repository(repository_url: &str, target_dir: &Path) -> Result<(), Error> {
  git2::Repository::clone(repository_url, target_dir).context("Cloning failed")?;
  Ok(())
}
```

```Rust
#[tauri::command(async)]
pub fn git_clone_repository(repository_url: &str, target_dir: &Path) -> Result<(), UnmarkedError> {
    let should_interrupt = AtomicBool::new(false);

    gix::prepare_clone(repository_url, target_dir)?
        .fetch_then_checkout(gix::progress::Discard, &should_interrupt)
        .map(|(checkout, _outcome)| checkout)?
        .main_worktree(gix::progress::Discard, &should_interrupt)?;
    Ok(())
}
```

--------------------------------

### Reproducing Race Conditions with Hyperfine

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/reports/22-03.md

Demonstrates how to use `hyperfine` to repeatedly execute a test binary, helping to reproduce and debug intermittent race conditions in the object database (ODB) initialization.

```Shell
hyperfine ./target/debug/<test>
```

--------------------------------

### Clone Git Repository with Gitoxide (Concise Implementation)

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/speak/gitmerge-2024.marp.md

The most concise implementation of `gix` repository cloning presented, leveraging the `?` operator for streamlined error handling and method chaining to reduce boilerplate code.

```Rust
#[tauri::command(async)]
pub fn git_clone_repository(repository_url: &str, target_dir: &Path) -> Result<(), UnmarkedError> {
    let should_interrupt = AtomicBool::new(false);

    gix::prepare_clone(repository_url, target_dir)?
        .fetch_then_checkout(gix::progress::Discard, &should_interrupt)
        .map(|(checkout, _outcome)| checkout)?
        .main_worktree(gix::progress::Discard, &should_interrupt)?;
    Ok(())
}
```

--------------------------------

### Convenience API Methods for gix::Repository and gix::Reference

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/reports/24-08.md

To simplify migration from `git2` to `gix`, new convenience methods have been added. `Repository` now offers direct `find_commit`, `find_tag`, `find_tree`, and `find_blob` methods, replacing the previous `find_object(id).try_into_<kind>()` pattern. `Reference` gains `peel_to_kind(kind)`, `peel_to_commit()`, `peel_to_tag()`, `peel_to_tree()`, and `peel_to_blob()` for direct object peeling, enhancing usability and quick object retrieval without refspecs.

```APIDOC
gix::Repository:
  find_commit(id: ObjectId) -> Result<Commit, Error>
  find_tag(id: ObjectId) -> Result<Tag, Error>
  find_tree(id: ObjectId) -> Result<Tree, Error>
  find_blob(id: ObjectId) -> Result<Blob, Error>

gix::Reference:
  peel_to_kind(kind: ObjectKind) -> Result<Object, Error>
  peel_to_commit() -> Result<Commit, Error>
  peel_to_tag() -> Result<Tag, Error>
  peel_to_tree() -> Result<Tree, Error>
  peel_to_blob() -> Result<Blob, Error>
```

--------------------------------

### gix Crate Top-Level Functionality

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/crate-status.md

Overview of core utilities provided by the `gix` crate, including interruptibility, timeouts, repository format handling, and unicode support for command-line arguments.

```APIDOC
gix:
  - utilities for applications to make long running operations interruptible gracefully and to support timeouts in servers.
  - handle core.repositoryFormatVersion and extensions
  - support for unicode-precomposition of command-line arguments (needs explicit use in parent application)
  - strict object creation (validate objects referenced by newly created objects exist)
  - strict hash verification (validate that objects actually have the hashes they claim to have)
```

--------------------------------

### Gitoxide: Worktree-Specific Configuration Layering

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/reports/22-12.md

Gitoxide now supports layering worktree-specific configuration on top of the shared repository configuration. This enhancement, contributed by Sidney, paves the way for correct and default support of sparse checkouts by making `gitoxide` aware of all `index` file features.

```APIDOC
Gitoxide Worktree Configuration:
  Feature: Layering worktree-specific configuration.
  Benefit: Enables correct support for sparse checkouts.
  Mechanism: Awareness of 'index' file features.
```

--------------------------------

### Git Config Conditional Include: onbranch

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/reports/22-06.md

Shows an example of the `onbranch:` conditional include pattern used in `git-config`. This pattern allows including configuration files based on the currently checked-out branch name.

```Git Config
onbranch:
```

--------------------------------

### Configure Shallow Clones and Fetches with gix CLI

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/reports/23-03.md

This snippet describes the command-line arguments available for `gix clone` and `gix fetch` to enable shallow repository operations, mirroring `git`'s equivalent functionality. These options allow users to perform shallow clones and fetches, reducing repository size and history by limiting the depth of the commit graph.

```CLI
gix clone --depth <N> <repository> <directory>
gix fetch --depth <N> <remote> <refspec>
```

--------------------------------

### gix-negotiate Crate Algorithms

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/crate-status.md

The `gix-negotiate` crate implements various negotiation algorithms. Currently, `noop`, `consecutive`, and `skipping` algorithms are supported.

```APIDOC
### gix-negotiate
* **algorithms**
  - [x] `noop`
  - [x] `consecutive`
  - [x] `skipping`
```

--------------------------------

### Git Config Conditional Include: gitdir/i

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/reports/22-06.md

Shows an example of the `gitdir/i:` conditional include pattern used in `git-config`. This pattern is similar to `gitdir:` but performs a case-insensitive match on the repository's `.git` directory path.

```Git Config
gitdir/i:
```

--------------------------------

### Publish Gitoxide Crate to Crates.io

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/COLLABORATING.md

For crates you own, use `cargo smart-release` to publish them to crates.io. This command ensures that dependencies are handled correctly during the publishing process.

```Shell
cargo smart-release
```

--------------------------------

### Git Config Conditional Include: gitdir

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/reports/22-06.md

Shows an example of the `gitdir:` conditional include pattern used in `git-config`. This pattern allows including configuration files based on the repository's `.git` directory path.

```Git Config
gitdir:
```

--------------------------------

### Clone Git Repository with Gitoxide (Verbose Implementation)

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/speak/gitmerge-2024.marp.md

This Rust function demonstrates cloning a Git repository using the `gix` library. It explicitly handles parsing the URL, preparing the clone, fetching, and checking out the main worktree, with detailed error contexts.

```Rust
#[tauri::command(async)]
pub fn git_clone_repository(repository_url: &str, target_dir: &Path) -> Result<(), Error> {
    let url =
        gix::url::parse(repository_url.into()).context("Failed to parse repository URL")?;
    let should_interrupt = AtomicBool::new(false);
    let mut prepared_clone =
        gix::prepare_clone(url, target_dir).context("Failed to prepare clone")?;
    let (mut prepared_checkout, _) = prepared_clone
        .fetch_then_checkout(Discard, &should_interrupt)
        .context("Failed to fetch")?;
    let should_interrupt = AtomicBool::new(false);
    prepared_checkout
        .main_worktree(Discard, &should_interrupt)
        .context("Failed to checkout main worktree")?;
    Ok(())
}
```

--------------------------------

### gix Repository Management

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/crate-status.md

Details on repository discovery, revision parsing, revision walking, instantiation, object access, and pathspec search within the `gix` crate.

```APIDOC
Repository:
  discovery:
    - option to not cross file systems (default)
    - handle git-common-dir
    - support for GIT_CEILING_DIRECTORIES environment variable
    - handle other non-discovery modes and provide control over environment variable usage required in applications
  rev-parse:
    - handle relative paths as relative to working directory
    - handle upstream and push resolution.
  rev-walk:
    - include tips
    - exclude commits
  instantiation
  access to refs and objects
  create a pathspec-search from a set of strings:
    - allow to construct Pathspecs using data structure instead of enforcing them to be passed as strings.
```

--------------------------------

### Explain Git Revision Specification with gix

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/reports/22-06.md

Demonstrates how to use the `gix repo revspec explain` command to verbalize the actions a revision specification performs, providing insight into its underlying logic. This command is repository-independent.

```Shell
gix repo revspec explain
```

--------------------------------

### Gix CLI: Cloning Repositories Without Tags (`--no-tags`)

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/reports/22-12.md

The `gix clone` command now supports a `--no-tags` flag. This allows users to perform a clone operation without fetching any tags, resulting in a more minimal repository, countering the default `auto-tags` behavior that mimics `git clone`.

```APIDOC
gix clone Command:
  --no-tags:
    Purpose: Prevents cloning of tags.
    Effect: Creates a more minimal repository.
    Default behavior: 'auto-tags' (similar to 'git clone').
```

--------------------------------

### Run Pre-Push Checks for Gitoxide Main Branch

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/COLLABORATING.md

Before pushing changes to the `main` branch, run these commands to ensure tests pass and the binary size check is performed, preventing CI breaks and warnings. It is recommended to use a pre-commit git hook for automation.

```Shell
just test check-size
```

```Shell
just check-size && git push
```

--------------------------------

### Raw Git Commit Object with ISO-8859-1 Encoding

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/gix-object/tests/fixtures/commit/with-encoding.txt

This snippet displays the raw content of a Git commit object. It includes the tree hash, parent commit hash, author and committer details with timestamps, the specified encoding (ISO-8859-1), and the commit message. This format is used internally by Git to represent commit data.

```Git Object Format
tree 4a1c03029e7407c0afe9fc0320b3258e188b115e
parent 7ca98aad461a5c302cb4c9e3acaaa6053cc67a62
author Sebastian Thiel <sebastian.thiel@icloud.com> 1592438199 +0800
committer Sebastian Thiel <sebastian.thiel@icloud.com> 1592438199 +0800
encoding ISO-8859-1

commit with encoding
```

--------------------------------

### Running ein tool hours with file and line statistics

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/reports/22-09.md

This command demonstrates how to execute the `ein tool hours` utility with options to collect file and line statistics. The tool is designed for high performance and low memory usage, aiming to be comparable to or better than `git shortlog -sne`.

```Shell
ein tool hours --file-stats --line-stats
```

--------------------------------

### Gitoxide Crate Stability Tiers Diagram

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/STABILITY.md

A schematic diagram illustrating the three stability tiers (Tier 1, Tier 2, Tier 3) used across gitoxide crates. It visualizes the hierarchical dependencies and relationships between different crate types, including plumbing, porcelain, core application functionality, and foundational crates, showing how they fit into the overall release software structure.

```text
                Release Software v1.X
    Stability Tier 1 ═════════════════════════════╗
    ║                                             ║
    ║    gix──────────────┐ ein──────────────┐    ║
    ║    │  plumbing app  │ │  porcelain app │    ║
    ║    └────────────────┘ └────────────────┘    ║
    ║             │                  │            ║
    ║             ▼                  ▼            ║
    ║    gitoxide-core───────────────────────┐    ║
    ║    │        application functionality  │    ║
    ║    └───────────────────────────────────┘    ║
    ║                      │                      ║
    ║                      ▼                      ║
    ║    gix   ──────────────────────────────┐    ║
    ║    │                application crate  │─ ─ ╬ ─
    ║    └───────────────────────────────────┘    ║  │
    ║                      │                      ║
    ║                      ▼                      ║  │
    ║    Foundation Crates───────────────────┐    ║
    ║    │ ┌─────────────┐   ┌─────────────┐ │    ║  │
    ║    │ │  gix-hash   │   │  gix-actor  │ │    ║
    ║    │ └─────────────┘   └─────────────┘ │    ║  │
    ║    │ ┌─────────────┐   ┌─────────────┐ │    ║
    ║    │ │   gix-ref   │   │ gix-config  │ │    ║  │
    ║    │ └─────────────┘   └─────────────┘ │    ║
    ║    │ ┌─────────────┐   ┌─────────────┐ │    ║  │
    ║    │ │ gix-object  │   │  gix-lock   │ │    ║
    ║    │ └─────────────┘   └─────────────┘ │    ║  │
    ║    │ ┌───────────────────────────────┐ │    ║
    ║    │ │         gix-features          │ │    ║  │
    ║    │ └───────────────────────────────┘ │    ║
    ║    └───────────────────────────────────┘    ║  │
    ║                                             ║
    ╚═════════════════════════════════════════════╝  │

    Stability Tier 2 ─────────────────────────────┐  │
    │                                             │
    │    Plumbing Crates─────────────────────┐    │  │
    │    │ ┌─────────────┐   ┌─────────────┐ │    │
    │    │ │   gix-odb   │   │  gix-diff   │ │    │  │
    │    │ └─────────────┘   └─────────────┘ │    │
    │    │ ┌─────────────┐   ┌─────────────┐ │    │  │
    │    │ │gix-traverse │   │  gix-pack   │ │◀ ─ ┼ ─
    │    │ └─────────────┘   └─────────────┘ │    │
    │    │ ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐ │    │
    │    │            …many more…            │    │
    │    │ └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘ │    │
    │    └───────────────────────────────────┘    │
    │                                             │
    └─────────────────────────────────────────────┘
```

--------------------------------

### Automating Releases with Cargo Smart-Release

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/reports/21-10.md

This command automatically determines the required version bump for each crate involved in a release and executes the release process, leveraging conventional commit messages for accurate versioning and safety bumps across the dependency graph.

```Rust
cargo smart-release --execute
```

--------------------------------

### Gitoxide: Fast Object Header Decoding for ODB Statistics (`repo.objects.header()`)

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/reports/22-12.md

The `repo.objects.header()` method was added to `gitoxide` to quickly enumerate object headers without full decoding, significantly speeding up object database statistics calculation. This method is approximately 8 times faster than full decoding and outperforms `git2`, enabling rapid analysis of large repositories like the Linux kernel.

```APIDOC
gix::Repository.objects.header():
  Purpose: Quickly enumerate object headers for statistics.
  Returns: An iterator or collection of object headers.
  Performance: ~8x faster than full object decoding.
```

--------------------------------

### Querying Git Attributes with gix attributes query

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/reports/23-05.md

Demonstrates how to use the `gix attributes query` command to print attributes for given paths, similar to `git check-attr` but with enhanced details including the match source and a more natural attribute display. This command helps in understanding how `.gitattributes` rules apply to specific files.

```Shell
gix attributes query tests/fixtures/generated-archives/foo.tar.xz
./.gitattributes:1:**/generated-archives/*.tar.xz       tests/fixtures/generated-archives/foo.tar.xz    diff=lfs
./.gitattributes:1:**/generated-archives/*.tar.xz       tests/fixtures/generated-archives/foo.tar.xz    merge=lfs
./.gitattributes:1:**/generated-archives/*.tar.xz       tests/fixtures/generated-archives/foo.tar.xz    -text
./.gitattributes:1:**/generated-archives/*.tar.xz       tests/fixtures/generated-archives/foo.tar.xz    filter=lfs
```

--------------------------------

### List available fuzzing targets

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/gix-refspec/README.md

Displays a list of all defined fuzzing targets within the `gix-refspec` project. This helps identify which specific components or functionalities can be fuzzed.

```Shell
cargo fuzz list
```

--------------------------------

### Gitoxide `gix index entries` Performance Comparison

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/etc/reports/23-08.md

Demonstrates the usage of the `gix index entries` command, which is Gitoxide's equivalent to `git ls-files`. This command showcases significant performance improvements (1.5x to 2.5x faster) over its Git counterpart due to the new pathspec matching engine.

```Shell
gix index entries
```

```Shell
git ls-files
```

--------------------------------

### gix-fs Module API

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/crate-status.md

The `gix-fs` module provides core filesystem abstractions and utilities, including capabilities probing, symlink management, and file snapshots.

```APIDOC
gix-fs Module:
  - probe_capabilities(): Probes filesystem capabilities. [x] Implemented.
  - symlink_creation_removal(): Supports symlink creation and removal. [x] Implemented.
  - file_snapshots(): Provides file snapshot functionality. [x] Implemented.
  - stack_abstraction(): Provides a stack abstraction. [x] Implemented.
```

--------------------------------

### gix-utils Module API

Source: https://github.com/gitoxidelabs/gitoxide/blob/main/crate-status.md

The `gix-utils` module offers various utility functions, particularly for filesystem interactions and string interning.

```APIDOC
gix-utils Module:
  - Filesystem Utilities:
    - probe_capabilities(): Probes filesystem capabilities. [x] Implemented.
    - symlink_creation_removal(): Supports symlink creation and removal. [x] Implemented.
    - file_snapshots(): Provides file snapshot functionality. [x] Implemented.
  - BString Interner: [ ] Planned, with Arena-Backing and arbitrary value association, potentially based on `internment` with `bumpalo` support.
```