git-vain/README.md

# git-vain

Generate vanity commit hashes quickly.

Supports:
- pgp signing (via gpg-agent or sequoia)
- integration with system key store for saving pgp passwords (sequoia only)
- arbitrary commits from history
- various methods (date increment/decrement, random text, counter text, header)
- multithreading
- config file for saving common options

## Install

Download the [latest release][] or build from source using `cargo`.

Make sure `git-vain` is in your `$PATH` or running `git vain` won't work.

To build from source, run `cargo install --path .` or `cargo build --release`
in your local checkout.

[latest release]: https://git.anna.lgbt/anna/git-vain/releases/latest

## Usage

Replace the hash of the commit at `HEAD` with one that begins with `c0ffee`:
`git vain c0ffee`

Try using `--help` for more information.

## Performance

Performance depends on hardware, method, and number of threads. The tests below
were performed on an AMD Ryzen 7 3800X 8-Core Processor. Each result is the
average of three trials running for 30 seconds using a single thread.

```
  counter: 154,293,195.67 hashes (5,143,106.52/s)
   random: 134,886,025.00 hashes (4,496,200.83/s)
   header: 131,035,925.67 hashes (4,367,864.19/s)
increment:  95,501,212.00 hashes (3,183,373.73/s)
decrement:  95,358,885.33 hashes (3,178,629.51/s)
 sequoia*:     839,872.67 hashes (   27,995.76/s)
  sequoia:     330,972.67 hashes (   11,032.42/s)
gpg-agent:         113.67 hashes (        3.79/s)
```
<small>The asterisked sequoia is using the `crypto-rust` feature.</small>

## Methods

`git-vain` can use one of several methods to generate different hashes for a
commit.

**Note that none of these are necessary when using PGP signing.** Since the
signature will be different every time, the hash will also be different every
time. If signing is enabled, none of these methods will be used.

### `increment` and `decrement`
Increases or decreases the commit's timestamp by one second each try. This is
not recommended for longer prefixes (or really at all, in the author's opinion).

### `counter`
Appends an increasing counter to the end of the commit message (in the body).

### `random`
Appends a random 32-character hexadecimal string to the end of the commit
message (in the body).

### `header`
Adds an additional `xvain` header to the commit, which contains an increasing
counter. Git ignores additional headers that aren't `gpgsig`, so this does work
and is considered valid by `git fsck`. In the author's opinion, it is doubtful
that Git would change the way headers are parsed, but it is possible, and that
would break this method (and possibly the commits created by it).

## PGP performance

Signing commits drastically reduces the speed at which `git-vain` operates. By
default, OpenSSL is used as the cryptography backend. For a moderate speedup
(see table above), you can use the RustCrypto libraries as the cryptography
backend instead. See the warnings below from sequoia.

> As of this writing, the RustCrypto crates are not recommended for general use
> as they cannot offer the same security guarantees as more mature cryptographic
> libraries.

> Some cryptographic backends can not guarantee that cryptographic operations
> require a constant amount of time.  This may leak secret keys in some
> settings.

The author cannot think of a scenario in which a timing attack would matter for
`git-vain`, but these warnings are worth acknowledging.

To use the RustCrypto libraries instead, compile with `cargo build --release
--no-default-features --features crypto-rust`.