Lutra/crates/engine/src/cmd/git_remote.rs
danny d097558ba5 M4.10: remotes: fetch, pull, push, clone and manage remotes
Owner decision D23: Lutra runs fetch, pull (merge or rebase per the new
git.pull.mode setting), push (upstream set on the first push) and clone
through the user's git. Any HTTPS or SSH server works; sign-in stays with
git's credential helper (its own window is allowed for network calls only)
and the ssh agent. Terminal prompts stay off, ext:: is refused, and URL
userinfo is redacted in every message, progress line and remote listing.

- vcs: Call::network with a 30 min timeout, a stderr progress sink and a
  Cancel flag that kills git's process group; remote.rs with clone_repo,
  fetch, pull, push (--porcelain rejections), remotes and add/set-url/
  remove; explained refusals (rejected push, sign-in, host key, not found,
  unreachable, no upstream, local changes, conflicts).
- engine: git.fetch/pull/push/clone/cancel/remotes/remoteAdd/remoteSetUrl/
  remoteRemove, one network call at a time, gitProgress events,
  gitChanged after changes.
- ui: status-bar progress with Cancel and ahead/behind, vcs.fetch/pull/
  push/clone/manageRemotes (Git menu, no default shortcuts), Clone
  Repository and Manage Remotes dialogs; desktop pick_dir IPC.
- Tests against local bare repositories only (vcs 8, engine 3, Vitest 11)
  plus unit and property tests; docs updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 17:50:26 +01:00

701 lines
22 KiB
Rust

//! Remote Git commands (M4.10, owner decision D23): fetch, pull, push,
//! clone, cancel, and the list of remotes with add, set-url and remove,
//! through the user's git (`lutra-vcs`).
//!
//! **Credentials stay with git.** HTTPS sign-in is git's credential
//! helper's (it may show its own window, such as Git Credential Manager's);
//! SSH uses the user's ssh with its agent and keys. Lutra never sees,
//! stores or logs a credential, terminal prompts are off, and URLs in
//! values, errors and progress have their userinfo redacted.
//!
//! **Off the lock.** Every command but `git.cancel` returns a pending
//! outcome: under the lock it parses its params and takes the setting; a
//! `lutra-git-remote` thread detects git, opens the project's repository
//! (`git.clone` needs none), runs the call and fills a reply slot. The
//! finish, under the lock again, emits `gitChanged` after a change.
//!
//! **One network call at a time.** fetch, pull, push and clone share one
//! slot; a second is refused while one runs. Its progress (git's
//! `--progress` lines) is kept by the thread and sent as `gitProgress`
//! from [`pump`] when it changed, so at most once per pump. `git.cancel`
//! sets its cancel flag: git and every process it started are killed and
//! the call fails with "cancelled". When the call ends, `gitProgress`
//! with `active: false` follows.
use std::path::PathBuf;
use std::sync::mpsc;
use std::sync::{Arc, Mutex, PoisonError};
use std::time::Duration;
use lutra_vcs::{Cancel, Git, Network, ProgressSink, PullMode, Remote, Repo, VcsError};
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use super::git::{EXECUTABLE_SETTING, GitChanged, RepoSummary};
use super::params::parse;
use crate::workspace::path_string;
use crate::{Command, CommandSpec, EngineError, Event, Outcome, Pending, Registry, State};
/// The setting choosing how `git.pull` joins the fetched commits.
pub const PULL_MODE_SETTING: &str = "git.pull.mode";
/// Longest wait for a call: detection and opening (30 s each) and the
/// network timeout, plus slack. The runner kills git first.
const WAIT: Duration = Duration::from_secs(30 * 60 + 120);
/// Registers the remote `git.*` commands.
///
/// # Errors
/// [`EngineError::Internal`] if an id is taken.
pub fn register(registry: &mut Registry) -> Result<(), EngineError> {
registry.register(Box::new(Fetch))?;
registry.register(Box::new(Pull))?;
registry.register(Box::new(Push))?;
registry.register(Box::new(CloneRepo))?;
registry.register(Box::new(CancelCommand))?;
registry.register(Box::new(Remotes))?;
registry.register(Box::new(RemoteAdd))?;
registry.register(Box::new(RemoteSetUrl))?;
registry.register(Box::new(RemoteRemove))?;
Ok(())
}
/// Payload of [`Event::GitProgress`]: the running network call and its
/// latest progress line.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct GitProgress {
/// A network call runs.
pub active: bool,
/// Which: `fetch`, `pull`, `push` or `clone`.
#[serde(skip_serializing_if = "Option::is_none")]
pub operation: Option<String>,
/// The phase of the latest line, e.g. `Receiving objects`, or the
/// whole line when it has no percentage.
#[serde(skip_serializing_if = "Option::is_none")]
pub phase: Option<String>,
/// The phase's percentage, when git printed one.
#[serde(skip_serializing_if = "Option::is_none")]
pub percent: Option<u8>,
}
/// The running network call.
#[derive(Debug)]
struct Active {
/// Which command runs.
operation: &'static str,
/// Stops it.
cancel: Cancel,
/// Its latest progress line, written by the reading thread.
latest: Arc<Mutex<Option<String>>>,
}
/// State of the remote commands.
#[derive(Debug, Default)]
pub struct GitRemote {
/// The running network call.
active: Option<Active>,
/// The `gitProgress` sent last, so an unchanged one is not sent again.
sent: Option<GitProgress>,
}
/// What one command does on its thread.
enum Op {
/// `git.fetch`.
Fetch(Option<String>),
/// `git.pull`.
Pull(PullMode),
/// `git.push`.
Push(Option<String>),
/// `git.clone`.
Clone {
/// The URL or path.
url: String,
/// The new work tree.
dir: PathBuf,
},
/// `git.remotes`.
Remotes,
/// `git.remoteAdd`.
Add(String, String),
/// `git.remoteSetUrl`.
SetUrl(String, String),
/// `git.remoteRemove`.
Remove(String),
}
impl Op {
/// The network operation's name; `None` for the local ones.
fn network(&self) -> Option<&'static str> {
match self {
Self::Fetch(_) => Some("fetch"),
Self::Pull(_) => Some("pull"),
Self::Push(_) => Some("push"),
Self::Clone { .. } => Some("clone"),
_ => None,
}
}
}
/// What a thread hands back to the finish.
struct Reply {
/// The command's value or error.
value: Result<Value, EngineError>,
/// After a successful change in the open project: its summary for
/// `gitChanged`.
changed: Option<RepoSummary>,
}
/// Turns a backend error into the engine's: the caller's mistakes are
/// `invalid_params`, everything else `failed`.
fn engine_error(command: &str, error: VcsError) -> EngineError {
if error.is_invalid_input() {
EngineError::invalid_params(command, error.to_string())
} else {
EngineError::Failed(error.to_string())
}
}
/// Runs `op` on a new thread and returns the pending outcome.
///
/// # Errors
/// [`EngineError::Disabled`] without a project (except for clone),
/// [`EngineError::Failed`] while another network call runs.
fn start(state: &mut State, command: &'static str, op: Op) -> Result<Outcome, EngineError> {
let project = state
.project
.as_ref()
.map(|w| w.project.root().to_path_buf());
if project.is_none() && !matches!(op, Op::Clone { .. }) {
return Err(EngineError::Disabled(command.to_string()));
}
let setting = state
.settings
.get(EXECUTABLE_SETTING)
.and_then(|v| v.as_str().map(str::to_string))
.unwrap_or_default();
let mut net = Network::default();
let mut slot_taken = false;
if let Some(operation) = op.network() {
if let Some(active) = &state.git_remote.active {
return Err(EngineError::Failed(format!(
"another Git operation is running ({}); wait for it or cancel it",
active.operation
)));
}
let cancel = Cancel::new();
let latest: Arc<Mutex<Option<String>>> = Arc::new(Mutex::new(None));
let writer = Arc::clone(&latest);
net = Network {
progress: Some(ProgressSink(Arc::new(move |line: &str| {
*writer.lock().unwrap_or_else(PoisonError::into_inner) = Some(line.to_string());
}))),
cancel: Some(cancel.clone()),
};
state.git_remote.active = Some(Active {
operation,
cancel,
latest,
});
state.git_remote.sent = None;
slot_taken = true;
}
let slot: Arc<Mutex<Option<Reply>>> = Arc::new(Mutex::new(None));
let (tx, rx) = mpsc::channel();
let filled = Arc::clone(&slot);
let thread_project = project.clone();
let spawned = std::thread::Builder::new()
.name("lutra-git-remote".into())
.spawn(move || {
let reply = work(command, &setting, thread_project, &op, &net);
*filled.lock().unwrap_or_else(PoisonError::into_inner) = Some(reply);
let _ = tx.send(Ok(Value::Null));
});
if let Err(e) = spawned {
if slot_taken {
state.git_remote.active = None;
}
return Err(EngineError::Failed(format!("cannot start git: {e}")));
}
Ok(Outcome::pending(Pending::new(rx, WAIT, move |state, _| {
if slot_taken {
finish_network(state);
}
let reply = slot
.lock()
.unwrap_or_else(PoisonError::into_inner)
.take()
.ok_or_else(|| EngineError::Failed("git did not answer in time".into()))?;
let current = state
.project
.as_ref()
.map(|w| w.project.root().to_path_buf());
if let Some(summary) = reply.changed
&& current.is_some()
&& current == project
{
state.emit(Event::GitChanged(GitChanged {
available: true,
repo: Some(summary),
files_changed: true,
}));
}
reply.value
})))
}
/// Frees the network slot and sends `gitProgress {active: false}`.
fn finish_network(state: &mut State) {
let Some(active) = state.git_remote.active.take() else {
return;
};
let done = GitProgress {
active: false,
operation: Some(active.operation.to_string()),
phase: None,
percent: None,
};
state.git_remote.sent = None;
state.emit(Event::GitProgress(done));
}
/// The thread's work: detect git, open the repository unless cloning, run
/// `op`.
fn work(
command: &'static str,
setting: &str,
project: Option<PathBuf>,
op: &Op,
net: &Network,
) -> Reply {
let fail = |value: EngineError| Reply {
value: Err(value),
changed: None,
};
let git = match Git::detect(setting) {
Ok(git) => git,
Err(e) => return fail(EngineError::Failed(e.to_string())),
};
if let Op::Clone { url, dir } = op {
return Reply {
value: git
.clone_repo(url, dir, net)
.map(|()| json!({"root": path_string(dir)}))
.map_err(|e| engine_error(command, e)),
changed: None,
};
}
let Some(project) = project else {
return fail(EngineError::Disabled(command.to_string()));
};
let repo = match git.open(&project) {
Ok(Some(repo)) => repo,
Ok(None) => {
return fail(EngineError::Failed(
"the project is not inside a Git repository".into(),
));
}
Err(e) => return fail(EngineError::Failed(e.to_string())),
};
let value = run_op(&repo, op, net).map_err(|e| engine_error(command, e));
let changed = (value.is_ok() && !matches!(op, Op::Remotes)).then(|| summary(&repo));
Reply { value, changed }
}
/// The repository summary for `gitChanged`; a failed query gives an empty
/// head (the event only asks clients to re-read).
fn summary(repo: &Repo) -> RepoSummary {
let head = repo.head().unwrap_or_default();
RepoSummary {
root: path_string(repo.root()),
branch: head.branch,
detached: head.detached,
head: head.head,
upstream: head.upstream,
ahead: head.ahead,
behind: head.behind,
}
}
/// One remote of `git.remotes`.
fn remote_json(remote: &Remote) -> Value {
let mut value = json!({"name": remote.name});
if let Some(map) = value.as_object_mut() {
if let Some(url) = &remote.fetch_url {
map.insert("fetchUrl".into(), json!(url));
}
if let Some(url) = &remote.push_url {
map.insert("pushUrl".into(), json!(url));
}
}
value
}
/// Runs one operation against the repository.
fn run_op(repo: &Repo, op: &Op, net: &Network) -> Result<Value, VcsError> {
match op {
Op::Fetch(remote) => repo.fetch(remote.as_deref(), net).map(|()| json!({})),
Op::Pull(mode) => repo.pull(*mode, net).map(|()| json!({})),
Op::Push(remote) => {
let pushed = repo.push(remote.as_deref(), net)?;
Ok(json!({
"remote": pushed.remote,
"branch": pushed.branch,
"upstreamSet": pushed.upstream_set,
}))
}
Op::Remotes => {
let remotes: Vec<Value> = repo.remotes()?.iter().map(remote_json).collect();
Ok(json!({"remotes": remotes}))
}
Op::Add(name, url) => repo.remote_add(name, url).map(|()| json!({})),
Op::SetUrl(name, url) => repo.remote_set_url(name, url).map(|()| json!({})),
Op::Remove(name) => repo.remote_remove(name).map(|()| json!({})),
Op::Clone { .. } => Err(VcsError::Git("clone needs no repository".into())),
}
}
/// Sends `gitProgress` when the running call's latest line changed.
/// Called from [`crate::Engine::pump_vfs`].
pub fn pump(state: &mut State) {
let Some(active) = &state.git_remote.active else {
return;
};
let line = active
.latest
.lock()
.unwrap_or_else(PoisonError::into_inner)
.clone();
let (phase, percent) = match line {
Some(line) => {
let (phase, percent) = lutra_vcs::parse_progress(&line);
(Some(phase), percent)
}
None => (None, None),
};
let now = GitProgress {
active: true,
operation: Some(active.operation.to_string()),
phase,
percent,
};
if state.git_remote.sent.as_ref() != Some(&now) {
state.git_remote.sent = Some(now.clone());
state.emit(Event::GitProgress(now));
}
}
/// Params of `git.fetch` and `git.push`.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct RemoteParams {
/// A remote's name; absent means all remotes (fetch) or the upstream's
/// (push).
#[serde(default)]
remote: Option<String>,
}
/// `git.fetch`.
struct Fetch;
impl Command for Fetch {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "git.fetch",
label: "Git: Fetch",
menu_path: None,
default_shortcut: None,
params: "{ remote?: remote name (all remotes when absent) }; returns {}; progress as gitProgress events, git.cancel stops it; sign-in through git's credential helper or ssh agent only",
}
}
fn enabled(&self, state: &State) -> bool {
state.has_project()
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: RemoteParams = parse(command, params)?;
start(state, command, Op::Fetch(p.remote))
}
}
/// How `git.pull` joins.
#[derive(Debug, Clone, Copy, Deserialize)]
#[serde(rename_all = "lowercase")]
enum ModeParam {
/// A merge.
Merge,
/// A rebase.
Rebase,
}
/// Params of `git.pull`.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct PullParams {
/// Overrides the `git.pull.mode` setting.
#[serde(default)]
mode: Option<ModeParam>,
}
/// `git.pull`.
struct Pull;
impl Command for Pull {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "git.pull",
label: "Git: Pull",
menu_path: None,
default_shortcut: None,
params: "{ mode?: \"merge\" | \"rebase\" (the git.pull.mode setting when absent) }; pulls the current branch's upstream; returns {}; refusals (no upstream, local changes, conflicts) explain themselves; progress as gitProgress events. Save dirty buffers first.",
}
}
fn enabled(&self, state: &State) -> bool {
state.has_project()
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: PullParams = parse(command, params)?;
let rebase = match p.mode {
Some(ModeParam::Rebase) => true,
Some(ModeParam::Merge) => false,
None => state
.settings
.get(PULL_MODE_SETTING)
.is_some_and(|v| v.as_str() == Some("rebase")),
};
let mode = if rebase {
PullMode::Rebase
} else {
PullMode::Merge
};
start(state, command, Op::Pull(mode))
}
}
/// `git.push`.
struct Push;
impl Command for Push {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "git.push",
label: "Git: Push",
menu_path: None,
default_shortcut: None,
params: "{ remote?: remote name for a branch without upstream (the only remote, else origin) }; pushes the current branch to its upstream, or sets one with the first push; returns { remote, branch, upstreamSet }; a rejected push explains itself; progress as gitProgress events",
}
}
fn enabled(&self, state: &State) -> bool {
state.has_project()
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: RemoteParams = parse(command, params)?;
start(state, command, Op::Push(p.remote))
}
}
/// Params of `git.clone`.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct CloneParams {
/// The URL (HTTPS, SSH, scp-like) or path.
url: String,
/// The new work tree: absolute, missing or empty.
dir: String,
}
/// `git.clone`.
struct CloneRepo;
impl Command for CloneRepo {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "git.clone",
label: "Git: Clone Repository",
menu_path: None,
default_shortcut: None,
params: "{ url: HTTPS, SSH or scp-like URL or a path, dir: absolute folder that is missing or empty (its parent must exist) }; returns { root }; works without a project; open it with project.open; progress as gitProgress events, git.cancel stops it and removes what it left",
}
}
fn enabled(&self, _state: &State) -> bool {
true
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: CloneParams = parse(command, params)?;
lutra_vcs::check_url(&p.url).map_err(|e| engine_error(command, e))?;
let dir = PathBuf::from(p.dir.trim());
if !dir.is_absolute() {
return Err(EngineError::invalid_params(
command,
"dir must be an absolute path",
));
}
start(state, command, Op::Clone { url: p.url, dir })
}
}
/// `git.cancel`.
struct CancelCommand;
impl Command for CancelCommand {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "git.cancel",
label: "Git: Cancel Fetch, Pull, Push or Clone",
menu_path: None,
default_shortcut: None,
params: "none; stops the running fetch, pull, push or clone (it then fails with \"cancelled\"); returns { cancelled: true }; disabled while none runs",
}
}
fn enabled(&self, state: &State) -> bool {
state.git_remote.active.is_some()
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let _: serde_json::Map<String, Value> = parse(self.spec().id, params)?;
let cancelled = state.git_remote.active.as_ref().is_some_and(|active| {
active.cancel.cancel();
true
});
Ok(Outcome::value(json!({"cancelled": cancelled})))
}
}
/// `git.remotes`.
struct Remotes;
impl Command for Remotes {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "git.remotes",
label: "Git: Remotes",
menu_path: None,
default_shortcut: None,
params: "none; returns { remotes: [{ name, fetchUrl?, pushUrl? }] } in config order; URLs with userinfo are redacted (https://***@host/…); pushUrl only when it differs",
}
}
fn enabled(&self, state: &State) -> bool {
state.has_project()
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let _: serde_json::Map<String, Value> = parse(command, params)?;
start(state, command, Op::Remotes)
}
}
/// Params of `git.remoteAdd` and `git.remoteSetUrl`.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct NameUrlParams {
/// The remote's name.
name: String,
/// Its URL or path.
url: String,
}
/// Params of `git.remoteRemove`.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct NameParams {
/// The remote's name.
name: String,
}
/// Checks a name and URL under the lock, so bad input fails at once.
fn check_name_url(command: &str, p: &NameUrlParams) -> Result<(), EngineError> {
lutra_vcs::check_remote_name(&p.name).map_err(|e| engine_error(command, e))?;
lutra_vcs::check_url(&p.url).map_err(|e| engine_error(command, e))
}
/// `git.remoteAdd`.
struct RemoteAdd;
impl Command for RemoteAdd {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "git.remoteAdd",
label: "Git: Add Remote",
menu_path: None,
default_shortcut: None,
params: "{ name, url }; adds a remote without fetching; returns {}",
}
}
fn enabled(&self, state: &State) -> bool {
state.has_project()
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: NameUrlParams = parse(command, params)?;
check_name_url(command, &p)?;
start(state, command, Op::Add(p.name, p.url))
}
}
/// `git.remoteSetUrl`.
struct RemoteSetUrl;
impl Command for RemoteSetUrl {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "git.remoteSetUrl",
label: "Git: Change Remote URL",
menu_path: None,
default_shortcut: None,
params: "{ name, url }; changes the remote's URL; returns {}",
}
}
fn enabled(&self, state: &State) -> bool {
state.has_project()
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: NameUrlParams = parse(command, params)?;
check_name_url(command, &p)?;
start(state, command, Op::SetUrl(p.name, p.url))
}
}
/// `git.remoteRemove`.
struct RemoteRemove;
impl Command for RemoteRemove {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "git.remoteRemove",
label: "Git: Remove Remote",
menu_path: None,
default_shortcut: None,
params: "{ name }; removes the remote with its remote-tracking branches; returns {}",
}
}
fn enabled(&self, state: &State) -> bool {
state.has_project()
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: NameParams = parse(command, params)?;
lutra_vcs::check_remote_name(&p.name).map_err(|e| engine_error(command, e))?;
start(state, command, Op::Remove(p.name))
}
}