git_bug/
lib.rs

1// git-bug-rs - A rust library for interfacing with git-bug repositories
2//
3// Copyright (C) 2024 Benedikt Peetz <benedikt.peetz@b-peetz.de>
4// Copyright (C) 2025 Benedikt Peetz <benedikt.peetz@b-peetz.de>
5// SPDX-License-Identifier: GPL-3.0-or-later
6//
7// This file is part of git-bug-rs/git-gub.
8//
9// You should have received a copy of the License along with this program.
10// If not, see <https://www.gnu.org/licenses/agpl.txt>.
11
12//! This crate provides the access to the git-bug data in a repository.
13//!
14//! Repository access is handled via the [`Replica`][`replica::Replica`]
15//! structure. This is also the main entry point to `git-bug-rs`.
16//!
17//! Beware that `git-bug-rs` currently *cannot* change the `git-bug` data. This
18//! is however planned.
19//!
20//! ### Quickstart
21//!
22//! #### Basic example
23//! The obvious use case of `git-bug-rs` is to read out all issues in a given
24//! replica. The following code will do just that.
25//!
26//! ```no_run
27//! # fn do_not_run_only_compile() {
28//! use crate::git_bug::replica::entity::Entity;
29//!
30//! git_bug::replica::Replica::from_path(".")
31//!     .unwrap()
32//!     .get_all::<git_bug::entities::issue::Issue>()
33//!     .unwrap()
34//!     .map(|maybe_issue| maybe_issue.unwrap().unwrap().snapshot())
35//!     .for_each(|issue_snapshot| println!("{}", issue_snapshot.title()));
36//! # }
37//! ```
38//!
39//! Notice, how we first constructed an
40//! iterator over the
41//! [`Issues`][`entities::issue::Issue`].
42//! Each [`Entity`][`replica::entity::Entity`] contains only their composing
43//! [`Operations`][`replica::entity::operation::operations::Operations`], to get
44//! the actual final value (in this case the titles), we first needed to
45//! [create][replica::entity::Entity::snapshot] a
46//! [snapshot][replica::entity::snapshot::Snapshot].
47//!
48//! This snapshot contains the full history of this specific
49//! [`Entity`][`replica::entity::Entity`] up to the point it was taken. It can
50//! be used to display the full history, e.g., when creating something similar
51//! to GitHub's issue timeline, or to calculate the final value.
52//!
53//! #### Working with the [`HistorySteps`][`HistoryStep`] in a [`Snapshot`]
54//!
55//! This will print out all the changes of an
56//! [`Identity's`][`entities::identity::Identity`] name and the id of the
57//! [`Identity`][`entities::identity::Identity`] that performed that change.
58//!
59//! ```no_run
60//! use crate::git_bug::replica::entity::Entity;
61//!
62//! # fn do_not_run_only_compile() -> Result<(), Box<dyn std::error::Error>> {
63//! let replica = git_bug::replica::Replica::from_path(".")?;
64//! replica
65//!     .get_all::<git_bug::entities::identity::Identity>()?
66//!     .map(|maybe_identity| maybe_identity.unwrap().unwrap().snapshot())
67//!     .for_each(|identity_snapshot| {
68//!         identity_snapshot
69//!             .timeline()
70//!             .name_history()
71//!             .for_each(|name_history_step| {
72//!                 println!(
73//!                     "{} changed the name of this identity to '{}'",
74//!                     replica
75//!                         .get::<git_bug::entities::identity::Identity>(
76//!                             name_history_step.author.id()
77//!                         )
78//!                         .unwrap()
79//!                         .snapshot(),
80//!                     name_history_step.name
81//!                 );
82//!             });
83//!     });
84//! # Ok(())
85//! # }
86//! ```
87//!
88//! ### Terminology
89//!
90//! #### `git-bug`
91//!
92//! Will mostly refer to the original go implementation of `git-bug`.
93//! `git-bug-rs` refers to this crate and `git-gub` to our own command line tool
94//! for interacting with `git-bug` repositories.
95//!
96//! #### `Issue`
97//!
98//! While `git-bug` refers to the data chains
99//! (DAGs) as “Bugs”, we refer to them as “Issues”.
100//! This makes the terminology clearer, as not every Issue is necessarily a bug (e.g., a feature
101//! request), whilst every bug is an issue.
102//!
103//! ## Serde support
104//!
105//! You will notice, that many types implement serde's Serialize and Deserialize traits.
106//! This is an unfortunate side effect of having to use serde for the cache de-/serialization.
107//! Some of these implies allow you to circumvent type invariants, as such, using them is not
108//! supported and they should be treated as implementation detail.
109//!
110//! Once, bitcode gets its `#[bitcode(with_serde)]` attribute back, we will probably migrate to
111//! that.
112// //! ### Feature Flags
113// #![cfg_attr(
114//     doc,
115//     doc = ::document_features::document_features!()
116// )]
117// #![cfg_attr(doc, feature(doc_cfg, doc_auto_cfg))]
118
119// Needed for the doc comment above.
120#[allow(unused_imports)]
121use replica::entity::snapshot::{Snapshot, timeline::history_step::HistoryStep};
122
123pub mod entities;
124pub mod query;
125pub mod replica;
git_bug/lib.rs

git_bug/
lib.rs
