diffler_core/vcs.rs
1//! Backend-agnostic VCS interface. Everything above this trait consumes
2//! `dyn Vcs`; only the `git` and `repo` modules (and test fixtures) may
3//! import git2.
4
5use std::path::{Path, PathBuf};
6
7use thiserror::Error;
8
9use crate::model::{DiffModel, HunkId};
10
11#[derive(Debug, Error)]
12pub enum VcsError {
13 // acceptable for M1; rework when a second backend lands
14 #[error(transparent)]
15 Git(#[from] git2::Error),
16 #[error("repository has no working directory")]
17 NoWorkdir,
18 /// Domain refusal, e.g. discarding a file with staged changes.
19 #[error("{0}")]
20 Rejected(String),
21 #[error(transparent)]
22 Io(#[from] std::io::Error),
23}
24
25#[derive(Debug, Clone, PartialEq, Eq)]
26pub struct HeadInfo {
27 /// Branch shorthand; `None` when HEAD is detached.
28 pub branch: Option<String>,
29 /// Abbreviated commit id; empty on an unborn branch.
30 pub oid7: String,
31 /// First line of the HEAD commit message; empty on an unborn branch.
32 pub subject: String,
33 /// Upstream branch shorthand, if configured.
34 pub upstream: Option<String>,
35 /// Commits on HEAD the upstream lacks, so work that exists only here is
36 /// visible without running `git status`. Zero without an upstream.
37 pub ahead: usize,
38 /// Commits on the upstream that HEAD lacks.
39 pub behind: usize,
40}
41
42#[derive(Debug, Clone, PartialEq, Eq)]
43pub struct LogEntry {
44 pub oid: String,
45 pub oid7: String,
46 /// Shorthand names of references pointing at this commit.
47 pub refs: Vec<String>,
48 pub subject: String,
49 pub author: String,
50 pub time_unix: i64,
51}
52
53#[derive(Debug, Clone, PartialEq, Eq)]
54pub struct BranchInfo {
55 pub name: String,
56 pub is_head: bool,
57 /// Tip commit's time as a Unix timestamp, so callers can sort branches
58 /// newest-first and render an age.
59 pub tip_unix: i64,
60 /// Commits on this branch its upstream lacks. Zero without an upstream.
61 pub ahead: usize,
62 /// Commits on the upstream this branch lacks. Zero without an upstream.
63 pub behind: usize,
64}
65
66/// A network operation the binary runs by shelling out to the backend's CLI,
67/// so the user's existing auth (SSH agent, credential helper, tokens) applies
68/// without diffler holding any credentials.
69#[derive(Debug, Clone, Copy, PartialEq, Eq)]
70pub enum NetworkOp {
71 Fetch,
72 FetchAll,
73}
74
75/// Per-area views of the working tree, neogit-style sections.
76#[derive(Debug, Clone, Default)]
77pub struct StatusModel {
78 pub untracked: DiffModel,
79 pub unstaged: DiffModel,
80 pub staged: DiffModel,
81}
82
83pub trait Vcs: Send {
84 /// Resolved repository metadata directory. In a plain repo this is
85 /// `<root>/.git`; in a linked worktree `<root>/.git` is a gitlink file
86 /// and this resolves to the external gitdir it points at.
87 fn git_dir(&self) -> Result<PathBuf, VcsError>;
88 /// Current branch, commit, and upstream.
89 fn head(&self) -> Result<HeadInfo, VcsError>;
90 /// Untracked / unstaged / staged sections as separate diff models.
91 fn status(&self) -> Result<StatusModel, VcsError>;
92 /// HEAD vs workdir+index including untracked files: the review view.
93 fn working_tree_diff(&self) -> Result<DiffModel, VcsError>;
94 /// [`Vcs::working_tree_diff`] taken from an arbitrary base commit instead
95 /// of HEAD, so uncommitted work shows alongside the commits since `base`.
96 fn tree_to_workdir_diff(&self, base_oid: &str) -> Result<DiffModel, VcsError>;
97 /// Changes a single commit introduced over its first parent.
98 fn commit_diff(&self, oid: &str) -> Result<DiffModel, VcsError>;
99 /// Combined diff of a contiguous commit range, from the first parent of
100 /// `oldest` to `newest` (`git diff <oldest>^..<newest>` semantics). When
101 /// `oldest` is a root commit its first-parent tree is the empty tree, so
102 /// the range includes everything `oldest` introduced.
103 fn range_diff(&self, oldest_oid: &str, newest_oid: &str) -> Result<DiffModel, VcsError>;
104 /// Diff between two trees as-is (`git diff <base> <newest>` semantics);
105 /// with `base` a merge base this is a PR-style three-dot diff.
106 fn tree_diff(&self, base_oid: &str, newest_oid: &str) -> Result<DiffModel, VcsError>;
107 /// Best common ancestor of two commits.
108 fn merge_base(&self, a: &str, b: &str) -> Result<String, VcsError>;
109 /// Resolve a revision (oid, ref name, remote ref) to a full commit oid.
110 fn resolve(&self, revision: &str) -> Result<String, VcsError>;
111 /// History from HEAD, newest first.
112 fn log(&self, limit: usize) -> Result<Vec<LogEntry>, VcsError>;
113
114 /// The branch a pull request merges into by default; `None` when the
115 /// repository offers no answer.
116 fn default_branch(&self, remote: &str) -> Result<Option<String>, VcsError>;
117
118 /// Commits reachable from `head` but not `base`, newest first: what a
119 /// pull request from `head` would carry.
120 fn commits_between(&self, base: &str, head: &str) -> Result<Vec<LogEntry>, VcsError>;
121 /// Commits on HEAD that no remote-tracking branch contains, newest first,
122 /// at most `limit` of them: work that exists only on this machine. `None`
123 /// when the repository has no remote-tracking refs, where being pushed has
124 /// no meaning yet. Asking the remotes rather than the configured upstream
125 /// is what makes the answer true: an upstream may be another local branch,
126 /// or a stale ref from before the last fetch. `limit` bounds a walk that is
127 /// otherwise the whole history whenever no remote ref sits on it.
128 fn unpushed(&self, limit: usize) -> Result<Option<Vec<LogEntry>>, VcsError>;
129 /// Local branches.
130 fn branches(&self) -> Result<Vec<BranchInfo>, VcsError>;
131 /// Local and remote-tracking branch names, for pickers that name a
132 /// revision rather than check one out.
133 fn all_branches(&self) -> Result<Vec<String>, VcsError>;
134 /// Stage a whole file (worktree deletions become staged deletions).
135 fn stage(&self, rel: &Path) -> Result<(), VcsError>;
136 /// Stage one hunk out of the unstaged (or untracked) changes of a file.
137 fn stage_hunk(&self, rel: &Path, hunk: &HunkId) -> Result<(), VcsError>;
138 /// Reset a file's index entry back to HEAD, keeping the worktree.
139 fn unstage(&self, rel: &Path) -> Result<(), VcsError>;
140 /// Remove one staged hunk from the index, keeping the worktree.
141 fn unstage_hunk(&self, rel: &Path, hunk: &HunkId) -> Result<(), VcsError>;
142 /// Throw away worktree changes only; an untracked file is deleted.
143 /// Refused while the file has staged changes (unstage first).
144 fn discard(&self, rel: &Path) -> Result<(), VcsError>;
145 /// Commit the index; returns the new commit id.
146 fn commit(&self, message: &str) -> Result<String, VcsError>;
147 /// Full message of the HEAD commit, for amend/reword editor templates.
148 fn head_message(&self) -> Result<String, VcsError>;
149 /// Amend HEAD, returning the new commit id. `message` `None` reuses HEAD's
150 /// message (extend); `Some` rewords it. `use_index` true folds the staged
151 /// index into the new tree (extend/amend); false keeps HEAD's tree (a
152 /// pure reword). Local-only: no network.
153 fn amend(&self, message: Option<&str>, use_index: bool) -> Result<String, VcsError>;
154 fn create_branch(&self, name: &str, checkout: bool) -> Result<(), VcsError>;
155 /// Refused for the currently checked-out branch.
156 fn delete_branch(&self, name: &str) -> Result<(), VcsError>;
157 fn checkout(&self, name: &str) -> Result<(), VcsError>;
158 /// Stash tracked changes (staged + unstaged), reverting the worktree to
159 /// HEAD; untracked files are left in place, matching `git stash`. `message`
160 /// `None` lets the backend label it. Local-only: no network.
161 fn stash_push(&self, message: Option<&str>) -> Result<(), VcsError>;
162 /// Restore the most recent stash and drop it. Refused when there is no
163 /// stash or the pop would conflict.
164 fn stash_pop(&self) -> Result<(), VcsError>;
165 /// Argv to run for a network op, e.g. `["git", "push"]`. The binary runs
166 /// this in [`Vcs::workdir`] so the backend's own CLI handles credentials;
167 /// diffler never touches them. A future jj backend returns `["jj", …]`.
168 fn network_argv(&self, op: NetworkOp) -> Vec<String>;
169 /// Working directory to run [`Vcs::network_argv`] in.
170 fn workdir(&self) -> Result<PathBuf, VcsError>;
171 /// URL of the named remote (e.g. `origin`), if it exists. Used to detect the
172 /// CI provider's host without shelling out.
173 fn remote_url(&self, name: &str) -> Result<Option<String>, VcsError>;
174 /// Names of every configured remote, for multi-remote CI detection.
175 fn remotes(&self) -> Result<Vec<String>, VcsError>;
176}
177
178/// Three-dot diff of `rev` against the working tree: `merge-base(rev, HEAD)`
179/// vs index + worktree + untracked. Commits `rev` gained since the branch
180/// forked stay out of it; uncommitted work stays in.
181pub fn against_diff(vcs: &dyn Vcs, rev: &str) -> Result<DiffModel, VcsError> {
182 let head = vcs.resolve("HEAD")?;
183 let base = vcs.merge_base(&vcs.resolve(rev)?, &head)?;
184 vcs.tree_to_workdir_diff(&base)
185}