git-bug 0.2.2

A rust library for interfacing with git-bug repositories
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

<!--
git-bug-rs - A rust library for interfacing with git-bug repositories

Copyright (C) 2025 Benedikt Peetz <benedikt.peetz@b-peetz.de>
SPDX-License-Identifier: GPL-3.0-or-later

This file is part of git-bug-rs/git-gub.

You should have received a copy of the License along with this program.
If not, see <https://www.gnu.org/licenses/agpl.txt>.
-->

# Git Bug Rs

> A rust library for interfacing with
> [git-bug](https://github.com/git-bug/git-bug) repositories.

## Features

<!-- - [Blazingly fast](./benchmarks.md) -->

- Complete access to all git-bug entities (e.g., `bugs`, `identities`).
- Extendable, to facilitate adding your own entities.
- All git object look-ups are backed by a transparent caching layer.
- Fully compliant with the go implementation (all divergences are bugs).
- Support for entity
  [queries](https://docs.rs/git-bug/latest/git_bug/query/struct.Query.html),
  which can also be constructed programmatically.
- Incremental entity loading. Only the requested entities are cached (i.e.,
  displaying the first 200 issues, will not need to load all issues into the
  cache)

## Quickstart

Take a look at the
[documentation](https://docs.rs/git_bug/latest/git_bug/index.html).

## Limitations

- Currently, creating and writing, entities is not (yet) possible.
- All entity look-ups are currently unstructured, which leads to a slightly
  lower [performance](#performance) than git-bug with it's caching layer.

## Performance

On a repository with 48889 issues (the `rust/rust-lang` issues imported into
git-bug), `git-gub issues list` takes around 5 seconds whilst `git-bug bug`
finishes in around 400 milliseconds. Without sorting `git-gub` finishes in
around 2 seconds. The reason for this performance difference comes down to the
missing cache layer, which means that we cannot leverage a query planner and
have suboptimal cache access patterns.

Run `cargo xtask bench-compare <repo with lots of issues> --poop --hyperfine` to
reproduce these.

## Roadmap

1. Entity creation and write support.
1. Support for structured access and a caching layer.
1. Zerocopy cache entry deserialization.
1. Performance equality with `git-bug`.

<!-- ## Why -->

## Credits

- The original [git-bug implementation](https://github.com/git-bug/git-bug)
  (parts of it have been directly translated (e.g., the entity read code))
- [`Gitoxide`](https://github.com/GitoxideLabs/gitoxide), which provides the
  base for `git-bug-rs`.
- [`Taskchampion`](https://github.com/GothenburgBitFactory/taskchampion), which
  was a huge inspiration for writing a good API, for entities based on
  operations.

## Licensing

This project complies with the REUSE v3.3 specification. This means that every
file clearly states its copyright.