diffler_core/vcs.rs
1//! Backend-agnostic VCS interface. Everything above this trait consumes
2//! `dyn Vcs`; only the `git` module (and test fixtures) may import git2.
3
4use std::path::{Path, PathBuf};
5
6use thiserror::Error;
7
8use crate::model::{DiffModel, HunkId};
9
10#[derive(Debug, Error)]
11pub enum VcsError {
12 // acceptable for M1; rework when a second backend lands
13 #[error(transparent)]
14 Git(#[from] git2::Error),
15 #[error("repository has no working directory")]
16 NoWorkdir,
17 /// Domain refusal, e.g. discarding a file with staged changes.
18 #[error("{0}")]
19 Rejected(String),
20 #[error(transparent)]
21 Io(#[from] std::io::Error),
22}
23
24#[derive(Debug, Clone, PartialEq, Eq)]
25pub struct HeadInfo {
26 /// Branch shorthand; `None` when HEAD is detached.
27 pub branch: Option<String>,
28 /// Abbreviated commit id; empty on an unborn branch.
29 pub oid7: String,
30 /// First line of the HEAD commit message; empty on an unborn branch.
31 pub subject: String,
32 /// Upstream branch shorthand, if configured.
33 pub upstream: Option<String>,
34}
35
36#[derive(Debug, Clone, PartialEq, Eq)]
37pub struct LogEntry {
38 pub oid: String,
39 pub oid7: String,
40 /// Shorthand names of references pointing at this commit.
41 pub refs: Vec<String>,
42 pub subject: String,
43 pub author: String,
44 pub time_unix: i64,
45}
46
47#[derive(Debug, Clone, PartialEq, Eq)]
48pub struct BranchInfo {
49 pub name: String,
50 pub is_head: bool,
51}
52
53/// A network operation the binary runs by shelling out to the backend's CLI,
54/// so the user's existing auth (SSH agent, credential helper, tokens) applies
55/// without diffler holding any credentials.
56#[derive(Debug, Clone, Copy, PartialEq, Eq)]
57pub enum NetworkOp {
58 Push,
59 PushSetUpstream,
60 Pull,
61 Fetch,
62 FetchAll,
63}
64
65/// Per-area views of the working tree, neogit-style sections.
66#[derive(Debug, Clone, Default)]
67pub struct StatusModel {
68 pub untracked: DiffModel,
69 pub unstaged: DiffModel,
70 pub staged: DiffModel,
71}
72
73pub trait Vcs: Send {
74 /// Resolved repository metadata directory. In a plain repo this is
75 /// `<root>/.git`; in a linked worktree `<root>/.git` is a gitlink file
76 /// and this resolves to the external gitdir it points at.
77 fn git_dir(&self) -> Result<PathBuf, VcsError>;
78 /// Current branch, commit, and upstream.
79 fn head(&self) -> Result<HeadInfo, VcsError>;
80 /// Untracked / unstaged / staged sections as separate diff models.
81 fn status(&self) -> Result<StatusModel, VcsError>;
82 /// HEAD vs workdir+index including untracked files: the review view.
83 fn working_tree_diff(&self) -> Result<DiffModel, VcsError>;
84 /// Changes a single commit introduced over its first parent.
85 fn commit_diff(&self, oid: &str) -> Result<DiffModel, VcsError>;
86 /// Combined diff of a contiguous commit range, from the first parent of
87 /// `oldest` to `newest` (`git diff <oldest>^..<newest>` semantics). When
88 /// `oldest` is a root commit its first-parent tree is the empty tree, so
89 /// the range includes everything `oldest` introduced.
90 fn range_diff(&self, oldest_oid: &str, newest_oid: &str) -> Result<DiffModel, VcsError>;
91 /// History from HEAD, newest first.
92 fn log(&self, limit: usize) -> Result<Vec<LogEntry>, VcsError>;
93 /// Local branches.
94 fn branches(&self) -> Result<Vec<BranchInfo>, VcsError>;
95 /// Stage a whole file (worktree deletions become staged deletions).
96 fn stage(&self, rel: &Path) -> Result<(), VcsError>;
97 /// Stage one hunk out of the unstaged (or untracked) changes of a file.
98 fn stage_hunk(&self, rel: &Path, hunk: &HunkId) -> Result<(), VcsError>;
99 /// Reset a file's index entry back to HEAD, keeping the worktree.
100 fn unstage(&self, rel: &Path) -> Result<(), VcsError>;
101 /// Remove one staged hunk from the index, keeping the worktree.
102 fn unstage_hunk(&self, rel: &Path, hunk: &HunkId) -> Result<(), VcsError>;
103 /// Throw away worktree changes only; an untracked file is deleted.
104 /// Refused while the file has staged changes (unstage first).
105 fn discard(&self, rel: &Path) -> Result<(), VcsError>;
106 /// Commit the index; returns the new commit id.
107 fn commit(&self, message: &str) -> Result<String, VcsError>;
108 /// Full message of the HEAD commit, for amend/reword editor templates.
109 fn head_message(&self) -> Result<String, VcsError>;
110 /// Amend HEAD, returning the new commit id. `message` `None` reuses HEAD's
111 /// message (extend); `Some` rewords it. `use_index` true folds the staged
112 /// index into the new tree (extend/amend); false keeps HEAD's tree (a
113 /// pure reword). Local-only — no network.
114 fn amend(&self, message: Option<&str>, use_index: bool) -> Result<String, VcsError>;
115 fn create_branch(&self, name: &str, checkout: bool) -> Result<(), VcsError>;
116 /// Refused for the currently checked-out branch.
117 fn delete_branch(&self, name: &str) -> Result<(), VcsError>;
118 fn checkout(&self, name: &str) -> Result<(), VcsError>;
119 /// Stash tracked changes (staged + unstaged), reverting the worktree to
120 /// HEAD; untracked files are left in place, matching `git stash`. `message`
121 /// `None` lets the backend label it. Local-only — no network.
122 fn stash_push(&self, message: Option<&str>) -> Result<(), VcsError>;
123 /// Restore the most recent stash and drop it. Refused when there is no
124 /// stash or the pop would conflict.
125 fn stash_pop(&self) -> Result<(), VcsError>;
126 /// Argv to run for a network op, e.g. `["git", "push"]`. The binary runs
127 /// this in [`Vcs::workdir`] so the backend's own CLI handles credentials;
128 /// diffler never touches them. A future jj backend returns `["jj", …]`.
129 fn network_argv(&self, op: NetworkOp) -> Vec<String>;
130 /// Working directory to run [`Vcs::network_argv`] in.
131 fn workdir(&self) -> Result<PathBuf, VcsError>;
132}