Skip to main content

grit_lib/
bundle_remote.rs

1//! Fetch and remote helpers for on-disk bundle files (clone / `grit fetch` from a `.bundle`).
2
3#![allow(dead_code)]
4
5use std::collections::HashSet;
6use std::fs::File;
7use std::io::{BufWriter, Write};
8use std::path::Path;
9
10use crate::bundle::{Bundle, BundleError, BundleSpec};
11use crate::error::{Error, Result};
12use crate::objects::ObjectId;
13use crate::progress::ProgressSink;
14use crate::remote::RemoteError;
15use crate::repo::Repository;
16use crate::transfer::{
17    apply_tag_mode, classify_update, prune_tracking_refs, FetchOptions, FetchOutcome, RefUpdate,
18    TagMode, TransferStats, UpdateMode,
19};
20
21const V2_SIGNATURE: &[u8] = b"# v2 git bundle\n";
22const V3_SIGNATURE: &[u8] = b"# v3 git bundle\n";
23
24/// Whether `path` begins with a v2 or v3 git bundle signature.
25#[must_use]
26pub fn is_bundle_path(path: &Path) -> bool {
27    let Ok(bytes) = std::fs::read(path) else {
28        return false;
29    };
30    bytes.starts_with(V2_SIGNATURE) || bytes.starts_with(V3_SIGNATURE)
31}
32
33/// Ref tips and revision tokens for
34/// [`RepositoryBundles::write_from_revs`](crate::repo_handles::RepositoryBundles::write_from_revs).
35#[derive(Debug, Clone, Default, PartialEq, Eq)]
36pub struct BundleCreateOptions {
37    /// When true, list `HEAD` and every ref under `refs/` in the bundle header (like `git bundle create --all`).
38    pub all_refs: bool,
39    /// Revision arguments (tips, ranges, exclusions). Ignored when `all_refs` is true.
40    pub rev_tokens: Vec<String>,
41}
42
43impl BundleCreateOptions {
44    /// Build options from positional revision tokens only.
45    #[must_use]
46    pub fn from_rev_tokens(rev_tokens: Vec<String>) -> Self {
47        Self {
48            all_refs: false,
49            rev_tokens,
50        }
51    }
52}
53
54/// Resolve [`BundleSpec`] from create options without writing a file.
55///
56/// When [`BundleCreateOptions::all_refs`] is true (or `--all` appears among `rev_tokens`), the bundle
57/// header lists `HEAD` and every ref under `refs/`, matching `git bundle create --all`.
58/// Only commits are walked here; objects are enumerated once, by the pack writer.
59///
60/// # Errors
61///
62/// Propagates rev-list, ref resolution, and empty-ref failures.
63pub fn resolve_bundle_spec(repo: &Repository, options: &BundleCreateOptions) -> Result<BundleSpec> {
64    let (rev_tokens, all_from_token) = strip_all_rev_flag(&options.rev_tokens);
65    let all_refs = options.all_refs || all_from_token;
66
67    let (positive_specs, negative_specs) = split_revision_specs_for_bundle(&rev_tokens);
68
69    if positive_specs.is_empty() && !all_refs {
70        return Err(BundleError::NoRevisions.into());
71    }
72
73    // With nothing excluded there is no boundary, so every ref is a tip and the pack
74    // writer's object walk is the only history walk needed.
75    if all_refs && positive_specs.is_empty() && negative_specs.is_empty() {
76        let include = refs_for_bundle_header(repo)?;
77        if include.is_empty() {
78            return Err(map_bundle_err(BundleError::EmptyRefs));
79        }
80        return Ok(BundleSpec {
81            include,
82            exclude: Vec::new(),
83            filter: None,
84        });
85    }
86
87    let rev_opts = crate::rev_list::RevListOptions {
88        boundary: true,
89        all_refs,
90        ..Default::default()
91    };
92    let revs = crate::rev_list::rev_list(repo, &positive_specs, &negative_specs, &rev_opts)?;
93
94    let include = if all_refs {
95        refs_for_bundle_header(repo)?
96    } else {
97        include_refs_from_rev_specs(repo, &positive_specs, &negative_specs, &revs)?
98    };
99
100    if include.is_empty() {
101        return Err(map_bundle_err(BundleError::EmptyRefs));
102    }
103
104    Ok(BundleSpec {
105        include,
106        exclude: revs.boundary_commits.clone(),
107        filter: None,
108    })
109}
110
111/// Write `spec` to `path`, replacing any existing file only after a successful pack stream.
112///
113/// On failure or cancel, removes the temporary `*.bundle.part` file and leaves an existing
114/// destination byte-for-byte unchanged. A panic during the write also removes the part file;
115/// SIGKILL may leave only the part file.
116///
117/// # Errors
118///
119/// Propagates [`BundleError`] from header/pack generation, including [`BundleError::ObjectNotFound`].
120pub(crate) fn write_bundle_spec_to_path(
121    repo: &Repository,
122    spec: &BundleSpec,
123    path: &Path,
124    progress: &mut dyn ProgressSink,
125    cancel: &crate::progress::CancelToken,
126) -> std::result::Result<usize, BundleError> {
127    let temp = path.with_extension("bundle.part");
128    if temp.exists() {
129        std::fs::remove_file(&temp).map_err(BundleError::from)?;
130    }
131    struct PartCleanup<'a>(&'a Path);
132    impl Drop for PartCleanup<'_> {
133        fn drop(&mut self) {
134            let _ = std::fs::remove_file(self.0);
135        }
136    }
137    let _cleanup = PartCleanup(&temp);
138    let file = File::create(&temp).map_err(BundleError::from)?;
139    let mut out = BufWriter::new(file);
140    crate::bundle::write_bundle(repo, spec, &mut out, progress, cancel)?;
141    out.flush().map_err(BundleError::from)?;
142    crate::atomic_replace::replace_file(&temp, path).map_err(BundleError::from)?;
143    std::mem::forget(_cleanup);
144    Ok(spec.include.len())
145}
146
147fn strip_all_rev_flag(tokens: &[String]) -> (Vec<String>, bool) {
148    let mut rev_tokens = Vec::new();
149    let mut all_refs = false;
150    for token in tokens {
151        if token == "--all" {
152            all_refs = true;
153        } else {
154            rev_tokens.push(token.clone());
155        }
156    }
157    (rev_tokens, all_refs)
158}
159
160fn refs_for_bundle_header(repo: &Repository) -> Result<Vec<(ObjectId, String)>> {
161    let mut include = Vec::new();
162    if let Ok(head) = crate::refs::resolve_ref(repo.git_dir(), "HEAD") {
163        include.push((head, "HEAD".to_owned()));
164    }
165    for (name, oid) in crate::refs::list_refs(repo.git_dir(), "refs/")? {
166        include.push((oid, name));
167    }
168    Ok(include)
169}
170
171fn include_refs_from_rev_specs(
172    repo: &Repository,
173    positive_specs: &[String],
174    negative_specs: &[String],
175    revs: &crate::rev_list::RevListResult,
176) -> Result<Vec<(ObjectId, String)>> {
177    let commits: HashSet<ObjectId> = revs.commits.iter().copied().collect();
178    let excluded: HashSet<ObjectId> = negative_specs
179        .iter()
180        .filter_map(|spec| crate::rev_parse::resolve_revision(repo, spec).ok())
181        .collect();
182    // A commit tip is bundled when that commit is sent. An annotated tag (or a tree or
183    // blob) is bundled unless it is excluded itself, even when its commit is a
184    // prerequisite: the recipient still needs the tag object and ref.
185    let tip_is_sent = |oid: ObjectId| match repo.odb().peel_tags(oid) {
186        Ok((commit, crate::objects::ObjectKind::Commit)) if commit == oid => {
187            commits.contains(&commit)
188        }
189        Ok(_) => !excluded.contains(&oid),
190        Err(_) => false,
191    };
192    let mut include: Vec<(ObjectId, String)> = Vec::new();
193    for spec in positive_specs {
194        if let Ok(oid) = crate::rev_parse::resolve_revision(repo, spec) {
195            if tip_is_sent(oid) {
196                let name = display_ref_for_spec(repo, spec, oid)?;
197                if !include.iter().any(|(_, n)| n == &name) {
198                    include.push((oid, name));
199                }
200            }
201        }
202    }
203    if include.is_empty() {
204        for oid in &revs.commits {
205            include.push((*oid, format!("refs/heads/bundle-tip/{}", oid.to_hex())));
206        }
207    }
208    Ok(include)
209}
210
211fn display_ref_for_spec(repo: &Repository, spec: &str, _oid: ObjectId) -> Result<String> {
212    if spec.starts_with("refs/") {
213        return Ok(spec.to_owned());
214    }
215    let exists = |name: &str| crate::refs::resolve_ref(repo.git_dir(), name).is_ok();
216    if let Some(name) = crate::worktree_ref::sole_dwim_ref_name(exists, spec) {
217        return Ok(name);
218    }
219    Ok(format!("refs/heads/{}", spec.trim_start_matches("heads/")))
220}
221
222/// Split CLI revision tokens into positive and negative specs for bundle creation.
223#[must_use]
224pub fn split_revision_specs_for_bundle(tokens: &[String]) -> (Vec<String>, Vec<String>) {
225    let mut positive = Vec::new();
226    let mut negative = Vec::new();
227    for token in tokens {
228        let (mut pos, mut neg) = crate::rev_list::split_revision_token(token);
229        positive.append(&mut pos);
230        negative.append(&mut neg);
231    }
232    (positive, negative)
233}
234
235/// Fetch from the bundle at `bundle_path` into `repo` (like `git fetch` from a bundle),
236/// unbundling into `repo`'s object store.
237pub(crate) fn fetch_from_bundle_into(
238    repo: &Repository,
239    bundle_path: &Path,
240    opts: &FetchOptions,
241    progress: &mut dyn crate::progress::ProgressSink,
242    cancel: &crate::progress::CancelToken,
243) -> Result<FetchOutcome> {
244    crate::progress::poll_cancel(progress, cancel)?;
245    let bundle = Bundle::open(bundle_path).map_err(map_bundle_err)?;
246    preflight_bundle_fetch_refspecs(&bundle, opts)?;
247    bundle
248        .verify(repo)
249        .map_err(map_bundle_err)?
250        .into_result()
251        .map_err(map_bundle_err)?;
252
253    let (transfer, pack_oids) = if opts.dry_run {
254        (TransferStats::default(), HashSet::new())
255    } else {
256        crate::progress::poll_cancel(progress, cancel)?;
257        let unbundled = bundle
258            .unbundle(repo, progress, cancel)
259            .map_err(map_bundle_err)?;
260        crate::progress::poll_cancel(progress, cancel)?;
261        (unbundled.transfer, unbundled.pack_object_ids)
262    };
263
264    let header = bundle.header();
265    let remote_refs = header.refs.clone();
266    let init_default_branch = repo.config().snapshot().ok().and_then(|cfg| {
267        cfg.get_last_entry("init.defaultBranch")
268            .and_then(|e| e.value.clone())
269            .filter(|s| !s.is_empty())
270    });
271    let default_branch =
272        default_branch_from_bundle_head(&header.refs, init_default_branch.as_deref());
273
274    let mut effective = opts.clone();
275    if effective.remote_name.is_none() && effective.fetch_source.is_none() {
276        effective.fetch_source = Some(bundle_path.to_string_lossy().into_owned());
277    }
278
279    crate::progress::poll_cancel(progress, cancel)?;
280    complete_bundle_fetch(
281        repo,
282        &remote_refs,
283        default_branch,
284        &effective,
285        &HashSet::new(),
286        pack_oids,
287        transfer,
288    )
289}
290
291/// Branch short name to check out after cloning from a bundle, from the bundle `HEAD` OID.
292///
293/// Matches Git's `guess_remote_head` when `HEAD` is not a symref.
294fn default_branch_from_bundle_head(
295    refs: &[(String, ObjectId)],
296    init_default_branch: Option<&str>,
297) -> Option<String> {
298    let head_oid = refs
299        .iter()
300        .find(|(name, _)| name == "HEAD")
301        .map(|(_, oid)| *oid)?;
302
303    if let Some(name) = init_default_branch {
304        if bundle_branch_tip_matches(refs, name, head_oid) {
305            return Some(name.to_owned());
306        }
307    }
308
309    if init_default_branch != Some("master") && bundle_branch_tip_matches(refs, "master", head_oid)
310    {
311        return Some("master".to_owned());
312    }
313
314    for (name, oid) in refs.iter().rev() {
315        if name == "HEAD" {
316            continue;
317        }
318        if let Some(short) = name.strip_prefix("refs/heads/") {
319            if *oid == head_oid {
320                return Some(short.to_owned());
321            }
322        }
323    }
324    None
325}
326
327fn bundle_branch_tip_matches(
328    refs: &[(String, ObjectId)],
329    branch: &str,
330    head_oid: ObjectId,
331) -> bool {
332    let full = format!("refs/heads/{branch}");
333    refs.iter()
334        .any(|(name, oid)| name == &full && *oid == head_oid)
335}
336
337#[allow(clippy::too_many_arguments)]
338fn complete_bundle_fetch(
339    local: &Repository,
340    remote_refs: &[(String, ObjectId)],
341    default_branch: Option<String>,
342    opts: &FetchOptions,
343    remote_shallow: &HashSet<ObjectId>,
344    pack_oids: HashSet<ObjectId>,
345    transfer: TransferStats,
346) -> Result<FetchOutcome> {
347    let local_git_dir = local.git_dir();
348    let local_odb = local.odb();
349    let remote_head_oid = crate::transfer::remote_head_oid_from_advertised(remote_refs);
350    let filtered_remote_refs: Vec<(String, ObjectId)> = remote_refs
351        .iter()
352        .filter(|(name, _)| {
353            name != "HEAD"
354                && !name.ends_with("^{}")
355                && crate::refs::is_valid_fetch_advertised_ref(name)
356        })
357        .cloned()
358        .collect();
359
360    let crate::transfer::FetchMatchSet {
361        mut matched,
362        positive,
363        negatives,
364        explicit_refspec_fetch,
365    } = crate::transfer::build_fetch_matched_set(opts, &filtered_remote_refs, remote_head_oid)?;
366    let mut matched_oids: HashSet<ObjectId> = matched.iter().map(|m| m.oid).collect();
367    let mut seen_remote_ref: HashSet<String> =
368        matched.iter().map(|m| m.remote_ref.clone()).collect();
369
370    let local_shallow = crate::shallow::load_shallow_boundaries(local_git_dir);
371    let mut tag_shallow = local_shallow.clone();
372    tag_shallow.extend(remote_shallow.iter().copied());
373
374    let tags_present = if opts.tags == TagMode::Following {
375        crate::fetch::tags_already_local(local.ref_store(), remote_refs)
376    } else {
377        HashSet::new()
378    };
379    let _following_only = apply_tag_mode(
380        opts.tags,
381        remote_refs,
382        local_odb,
383        &tag_shallow,
384        &negatives,
385        &tags_present,
386        opts.force,
387        &mut matched,
388        &mut matched_oids,
389        &mut seen_remote_ref,
390    )?;
391
392    if opts.tags == TagMode::Following {
393        crate::fetch::retain_following_tags(local_odb, &mut matched, &pack_oids, &local_shallow)?;
394    }
395
396    let local_repo = (!opts.dry_run).then_some(local);
397
398    let mut updates: Vec<RefUpdate> = Vec::new();
399    if opts.prune {
400        prune_tracking_refs(local, &positive, remote_refs, opts.dry_run, &mut updates)?;
401    }
402
403    let mut store_batch: Vec<(String, crate::refs::store::RawRef)> =
404        Vec::with_capacity(matched.len());
405    for m in &matched {
406        let Some(local_ref) = &m.local_ref else {
407            updates.push(RefUpdate {
408                remote_ref: m.remote_ref.clone(),
409                local_ref: None,
410                old_oid: None,
411                new_oid: Some(m.oid),
412                mode: UpdateMode::NoChangeNeeded,
413                note: Some("not stored (empty destination)".to_owned()),
414            });
415            continue;
416        };
417
418        let old = local.resolve_ref_oid(local_ref).ok();
419        let mode = classify_update(
420            old.as_ref(),
421            &m.oid,
422            m.force,
423            m.dest_is_tag,
424            local_repo,
425            None,
426        );
427
428        let write = matches!(
429            mode,
430            UpdateMode::New | UpdateMode::FastForward | UpdateMode::Forced
431        );
432        crate::transfer::enforce_fetch_ref_update(
433            local_ref,
434            old,
435            m.oid,
436            mode,
437            opts,
438            explicit_refspec_fetch,
439            local_repo,
440        )?;
441        if write && !opts.dry_run {
442            if !crate::refs::is_valid_storable_ref_name(local_ref) {
443                updates.push(RefUpdate {
444                    remote_ref: m.remote_ref.clone(),
445                    local_ref: Some(local_ref.clone()),
446                    old_oid: old,
447                    new_oid: Some(m.oid),
448                    mode,
449                    note: Some("skipped (invalid ref name)".to_owned()),
450                });
451                continue;
452            }
453            store_batch.push((local_ref.clone(), crate::refs::store::RawRef::Direct(m.oid)));
454        }
455
456        updates.push(RefUpdate {
457            remote_ref: m.remote_ref.clone(),
458            local_ref: Some(local_ref.clone()),
459            old_oid: old,
460            new_oid: Some(m.oid),
461            mode,
462            note: None,
463        });
464    }
465
466    if !opts.dry_run && !store_batch.is_empty() {
467        let fetch_reflog = crate::fetch::prepare_fetch_apply_reflog(local, opts)?;
468        let fetch_reflog_ctx = fetch_reflog
469            .as_ref()
470            .map(crate::fetch::PreparedFetchReflog::context);
471        crate::transfer::apply_fetch_ref_updates(
472            local,
473            store_batch,
474            &mut updates,
475            crate::transfer::FetchRefRejectHint {
476                prune: opts.prune,
477                positive: &positive,
478                remote_refs,
479                remote_name: opts.remote_name.as_deref(),
480            },
481            opts.initial_remote_fetch,
482            fetch_reflog_ctx.as_ref(),
483        )?;
484    }
485
486    crate::fetch::finish_initial_remote_fetch_layout(local, opts, default_branch.as_deref())?;
487    crate::transfer::finish_anonymous_url_fetch(
488        local_git_dir,
489        opts,
490        explicit_refspec_fetch,
491        default_branch.as_deref(),
492        remote_refs,
493        &matched,
494    )?;
495    let new_shallow = if opts.initial_remote_fetch {
496        remote_shallow.iter().copied().collect()
497    } else {
498        Vec::new()
499    };
500    Ok(FetchOutcome {
501        updates,
502        default_branch,
503        new_shallow,
504        new_unshallow: Vec::new(),
505        transfer,
506        filter_sent: false,
507        promisor: None,
508    })
509}
510
511/// Resolve fetch refspecs against the bundle header before ingesting objects.
512fn preflight_bundle_fetch_refspecs(bundle: &Bundle, opts: &FetchOptions) -> Result<()> {
513    use crate::fetch_request::FetchRefspecError;
514    use crate::remote::Remote;
515
516    let header_refs = &bundle.header().refs;
517    let effective = if opts.refspecs.is_empty() {
518        &opts.configured_refspecs
519    } else {
520        &opts.refspecs
521    };
522
523    let implicit_head_fetch = effective.is_empty()
524        || (effective.len() == 1
525            && effective[0].trim_start_matches('+') == Remote::ANONYMOUS_FETCH_REFSPEC);
526
527    if implicit_head_fetch {
528        if crate::transfer::remote_head_oid_from_advertised(header_refs).is_none() {
529            return Err(
530                RemoteError::FetchRefspec(FetchRefspecError::SourceNotFound {
531                    ref_name: "HEAD".to_owned(),
532                    spec: "HEAD".to_owned(),
533                })
534                .into(),
535            );
536        }
537        return Ok(());
538    }
539
540    let remote_head_oid = crate::transfer::remote_head_oid_from_advertised(header_refs);
541    let filtered_remote_refs: Vec<(String, ObjectId)> = header_refs
542        .iter()
543        .filter(|(name, _)| {
544            name != "HEAD"
545                && !name.ends_with("^{}")
546                && crate::refs::is_valid_fetch_advertised_ref(name)
547        })
548        .cloned()
549        .collect();
550    crate::transfer::build_fetch_matched_set(opts, &filtered_remote_refs, remote_head_oid)?;
551    Ok(())
552}
553
554fn map_bundle_err(e: BundleError) -> Error {
555    Error::from(e)
556}
557
558#[cfg(test)]
559mod tests {
560    use super::*;
561    use crate::environment::RepositoryOptions;
562    use crate::progress::NullProgress;
563
564    #[test]
565    fn default_branch_follows_bundle_head_not_first_branch_line() {
566        let main = ObjectId::from_hex("f04545002f192e3ffe2e2f6341abb0665215b0c8").unwrap();
567        let feature = ObjectId::from_hex("c48fa981db2b56e99fb87fc3c2827ee4b5186d8f").unwrap();
568        let refs = vec![
569            ("refs/heads/feature".into(), feature),
570            ("refs/heads/main".into(), main),
571            ("HEAD".into(), main),
572        ];
573        assert_eq!(
574            default_branch_from_bundle_head(&refs, None).as_deref(),
575            Some("main")
576        );
577    }
578
579    #[test]
580    fn split_revision_specs_handles_double_dot_range() {
581        let tokens = vec!["HEAD~1..HEAD".to_owned()];
582        let (pos, neg) = split_revision_specs_for_bundle(&tokens);
583        assert_eq!(pos, vec!["HEAD"]);
584        assert_eq!(neg, vec!["HEAD~1"]);
585    }
586
587    #[cfg_attr(
588        not(feature = "full-tests"),
589        ignore = "starts system git or is heavy; run with --features full-tests"
590    )]
591    #[test]
592    fn write_from_revs_records_tag_dwim_as_refs_tags() {
593        let tmp = tempfile::tempdir().expect("tempdir");
594        let dir = tmp.path();
595        std::process::Command::new("git")
596            .current_dir(dir)
597            .args(["init", "-q", "-b", "main", "."])
598            .env("GIT_CONFIG_GLOBAL", "/dev/null")
599            .env("GIT_CONFIG_SYSTEM", "/dev/null")
600            .status()
601            .expect("git init");
602        std::fs::write(dir.join("a.txt"), b"a\n").unwrap();
603        assert!(std::process::Command::new("git")
604            .current_dir(dir)
605            .args(["add", "a.txt"])
606            .env("GIT_CONFIG_GLOBAL", "/dev/null")
607            .env("GIT_CONFIG_SYSTEM", "/dev/null")
608            .status()
609            .unwrap()
610            .success());
611        assert!(std::process::Command::new("git")
612            .current_dir(dir)
613            .args([
614                "-c",
615                "user.name=T",
616                "-c",
617                "user.email=t@example.com",
618                "commit",
619                "-qm",
620                "one",
621            ])
622            .env("GIT_CONFIG_GLOBAL", "/dev/null")
623            .env("GIT_CONFIG_SYSTEM", "/dev/null")
624            .status()
625            .unwrap()
626            .success());
627        assert!(std::process::Command::new("git")
628            .current_dir(dir)
629            .args(["tag", "lite"])
630            .env("GIT_CONFIG_GLOBAL", "/dev/null")
631            .env("GIT_CONFIG_SYSTEM", "/dev/null")
632            .status()
633            .unwrap()
634            .success());
635
636        let repo = Repository::discover(Some(dir), &RepositoryOptions::empty()).expect("open repo");
637        let bundle_path = dir.join("t1.bundle");
638        repo.bundles()
639            .write_from_revs(
640                &BundleCreateOptions::from_rev_tokens(vec!["lite".to_owned(), "main".to_owned()]),
641                &bundle_path,
642                &mut NullProgress,
643                crate::progress::CancelToken::never_ref(),
644            )
645            .expect("write bundle");
646
647        let header = crate::bundle::Bundle::open(&bundle_path)
648            .expect("open bundle")
649            .header()
650            .clone();
651        let names: Vec<_> = header.refs.iter().map(|(n, _)| n.as_str()).collect();
652        assert!(
653            names.contains(&"refs/tags/lite"),
654            "expected refs/tags/lite in {names:?}"
655        );
656        assert!(
657            !names.contains(&"refs/heads/lite"),
658            "must not record tag as branch: {names:?}"
659        );
660        assert!(names.contains(&"refs/heads/main"));
661    }
662}