Crate git_bug

This crate provides the access to the git-bug data in a repository.

Repository access is handled via the Replica structure. This is also the main entry point to git-bug-rs.

Beware that git-bug-rs currently cannot change the git-bug data. This is however planned.

Quickstart

Basic example

The obvious use case of git-bug-rs is to read out all issues in a given replica. The following code will do just that.

use crate::git_bug::replica::entity::Entity;

git_bug::replica::Replica::from_path(".")
    .unwrap()
    .get_all::<git_bug::entities::issue::Issue>()
    .unwrap()
    .map(|maybe_issue| maybe_issue.unwrap().unwrap().snapshot())
    .for_each(|issue_snapshot| println!("{}", issue_snapshot.title()));

Notice, how we first constructed an iterator over the Issues. Each Entity contains only their composing Operations, to get the actual final value (in this case the titles), we first needed to create a snapshot.

This snapshot contains the full history of this specific Entity up to the point it was taken. It can be used to display the full history, e.g., when creating something similar to GitHub’s issue timeline, or to calculate the final value.

Working with the HistorySteps in a Snapshot

This will print out all the changes of an Identity's name and the id of the Identity that performed that change.

use crate::git_bug::replica::entity::Entity;

let replica = git_bug::replica::Replica::from_path(".")?;
replica
    .get_all::<git_bug::entities::identity::Identity>()?
    .map(|maybe_identity| maybe_identity.unwrap().unwrap().snapshot())
    .for_each(|identity_snapshot| {
        identity_snapshot
            .timeline()
            .name_history()
            .for_each(|name_history_step| {
                println!(
                    "{} changed the name of this identity to '{}'",
                    replica
                        .get::<git_bug::entities::identity::Identity>(
                            name_history_step.author.id()
                        )
                        .unwrap()
                        .snapshot(),
                    name_history_step.name
                );
            });
    });

Terminology

git-bug

Will mostly refer to the original go implementation of git-bug. git-bug-rs refers to this crate and git-gub to our own command line tool for interacting with git-bug repositories.

Issue

While git-bug refers to the data chains (DAGs) as “Bugs”, we refer to them as “Issues”. This makes the terminology clearer, as not every Issue is necessarily a bug (e.g., a feature request), whilst every bug is an issue.

Serde support

You will notice, that many types implement serde’s Serialize and Deserialize traits. This is an unfortunate side effect of having to use serde for the cache de-/serialization. Some of these implies allow you to circumvent type invariants, as such, using them is not supported and they should be treated as implementation detail.

Once, bitcode gets its #[bitcode(with_serde)] attribute back, we will probably migrate to that.

Modules

entities

All the Entities, that can be stored in a Replica.

query

The query language supported by git-bug-rs

replica

Handling of Replicas.

Macros

get

A helper macro for working with the (owned) simd_json::owned::Value.

impl_cache

Implement caching.