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}
36
37#[derive(Debug, Clone, PartialEq, Eq)]
38pub struct LogEntry {
39    pub oid: String,
40    pub oid7: String,
41    /// Shorthand names of references pointing at this commit.
42    pub refs: Vec<String>,
43    pub subject: String,
44    pub author: String,
45    pub time_unix: i64,
46}
47
48#[derive(Debug, Clone, PartialEq, Eq)]
49pub struct BranchInfo {
50    pub name: String,
51    pub is_head: bool,
52}
53
54/// A network operation the binary runs by shelling out to the backend's CLI,
55/// so the user's existing auth (SSH agent, credential helper, tokens) applies
56/// without diffler holding any credentials.
57#[derive(Debug, Clone, Copy, PartialEq, Eq)]
58pub enum NetworkOp {
59    Push,
60    PushSetUpstream,
61    Pull,
62    Fetch,
63    FetchAll,
64}
65
66/// Per-area views of the working tree, neogit-style sections.
67#[derive(Debug, Clone, Default)]
68pub struct StatusModel {
69    pub untracked: DiffModel,
70    pub unstaged: DiffModel,
71    pub staged: DiffModel,
72}
73
74pub trait Vcs: Send {
75    /// Resolved repository metadata directory. In a plain repo this is
76    /// `<root>/.git`; in a linked worktree `<root>/.git` is a gitlink file
77    /// and this resolves to the external gitdir it points at.
78    fn git_dir(&self) -> Result<PathBuf, VcsError>;
79    /// Current branch, commit, and upstream.
80    fn head(&self) -> Result<HeadInfo, VcsError>;
81    /// Untracked / unstaged / staged sections as separate diff models.
82    fn status(&self) -> Result<StatusModel, VcsError>;
83    /// HEAD vs workdir+index including untracked files: the review view.
84    fn working_tree_diff(&self) -> Result<DiffModel, VcsError>;
85    /// Changes a single commit introduced over its first parent.
86    fn commit_diff(&self, oid: &str) -> Result<DiffModel, VcsError>;
87    /// Combined diff of a contiguous commit range, from the first parent of
88    /// `oldest` to `newest` (`git diff <oldest>^..<newest>` semantics). When
89    /// `oldest` is a root commit its first-parent tree is the empty tree, so
90    /// the range includes everything `oldest` introduced.
91    fn range_diff(&self, oldest_oid: &str, newest_oid: &str) -> Result<DiffModel, VcsError>;
92    /// Diff between two trees as-is (`git diff <base> <newest>` semantics);
93    /// with `base` a merge base this is a PR-style three-dot diff.
94    fn tree_diff(&self, base_oid: &str, newest_oid: &str) -> Result<DiffModel, VcsError>;
95    /// Best common ancestor of two commits.
96    fn merge_base(&self, a: &str, b: &str) -> Result<String, VcsError>;
97    /// Resolve a revision (oid, ref name, remote ref) to a full commit oid.
98    fn resolve(&self, revision: &str) -> Result<String, VcsError>;
99    /// History from HEAD, newest first.
100    fn log(&self, limit: usize) -> Result<Vec<LogEntry>, VcsError>;
101    /// Local branches.
102    fn branches(&self) -> Result<Vec<BranchInfo>, VcsError>;
103    /// Stage a whole file (worktree deletions become staged deletions).
104    fn stage(&self, rel: &Path) -> Result<(), VcsError>;
105    /// Stage one hunk out of the unstaged (or untracked) changes of a file.
106    fn stage_hunk(&self, rel: &Path, hunk: &HunkId) -> Result<(), VcsError>;
107    /// Reset a file's index entry back to HEAD, keeping the worktree.
108    fn unstage(&self, rel: &Path) -> Result<(), VcsError>;
109    /// Remove one staged hunk from the index, keeping the worktree.
110    fn unstage_hunk(&self, rel: &Path, hunk: &HunkId) -> Result<(), VcsError>;
111    /// Throw away worktree changes only; an untracked file is deleted.
112    /// Refused while the file has staged changes (unstage first).
113    fn discard(&self, rel: &Path) -> Result<(), VcsError>;
114    /// Commit the index; returns the new commit id.
115    fn commit(&self, message: &str) -> Result<String, VcsError>;
116    /// Full message of the HEAD commit, for amend/reword editor templates.
117    fn head_message(&self) -> Result<String, VcsError>;
118    /// Amend HEAD, returning the new commit id. `message` `None` reuses HEAD's
119    /// message (extend); `Some` rewords it. `use_index` true folds the staged
120    /// index into the new tree (extend/amend); false keeps HEAD's tree (a
121    /// pure reword). Local-only — no network.
122    fn amend(&self, message: Option<&str>, use_index: bool) -> Result<String, VcsError>;
123    fn create_branch(&self, name: &str, checkout: bool) -> Result<(), VcsError>;
124    /// Refused for the currently checked-out branch.
125    fn delete_branch(&self, name: &str) -> Result<(), VcsError>;
126    fn checkout(&self, name: &str) -> Result<(), VcsError>;
127    /// Stash tracked changes (staged + unstaged), reverting the worktree to
128    /// HEAD; untracked files are left in place, matching `git stash`. `message`
129    /// `None` lets the backend label it. Local-only — no network.
130    fn stash_push(&self, message: Option<&str>) -> Result<(), VcsError>;
131    /// Restore the most recent stash and drop it. Refused when there is no
132    /// stash or the pop would conflict.
133    fn stash_pop(&self) -> Result<(), VcsError>;
134    /// Argv to run for a network op, e.g. `["git", "push"]`. The binary runs
135    /// this in [`Vcs::workdir`] so the backend's own CLI handles credentials;
136    /// diffler never touches them. A future jj backend returns `["jj", …]`.
137    fn network_argv(&self, op: NetworkOp) -> Vec<String>;
138    /// Working directory to run [`Vcs::network_argv`] in.
139    fn workdir(&self) -> Result<PathBuf, VcsError>;
140    /// URL of the named remote (e.g. `origin`), if it exists. Used to detect the
141    /// CI provider's host without shelling out.
142    fn remote_url(&self, name: &str) -> Result<Option<String>, VcsError>;
143    /// Names of every configured remote, for multi-remote CI detection.
144    fn remotes(&self) -> Result<Vec<String>, VcsError>;
145}
diffler_core/vcs.rs

diffler_core/
vcs.rs
