feat!: Allow checkouts of empty repositories

j-walther · Byron · commit e75fbfa8dbb5 · 2026-05-12T14:22:47.000+08:00
Also make turn `destination_must_be_empty` into `Option&lt;bool&gt;`
diff --git a/gix/src/clone/access.rs b/gix/src/clone/access.rs
@@ -73,7 +73,12 @@ impl PrepareFetch {
 impl Drop for PrepareFetch {
     fn drop(&mut self) {
         if let Some(repo) = self.repo.take() {
-            std::fs::remove_dir_all(repo.workdir().unwrap_or_else(|| repo.path())).ok();
+            if self.destination_was_empty {
+                std::fs::remove_dir_all(repo.workdir().unwrap_or_else(|| repo.path())).ok();
+            } else {
+                // The destination held pre-existing user files; only remove the `.git` we created.
+                std::fs::remove_dir_all(repo.path()).ok();
+            }
         }
     }
 }
diff --git a/gix/src/clone/checkout.rs b/gix/src/clone/checkout.rs
@@ -171,7 +171,12 @@ impl PrepareCheckout {
 impl Drop for PrepareCheckout {
     fn drop(&mut self) {
         if let Some(repo) = self.repo.take() {
-            std::fs::remove_dir_all(repo.workdir().unwrap_or_else(|| repo.path())).ok();
+            if self.destination_was_empty {
+                std::fs::remove_dir_all(repo.workdir().unwrap_or_else(|| repo.path())).ok();
+            } else {
+                // The destination held pre-existing user files; only remove the `.git` we created.
+                std::fs::remove_dir_all(repo.path()).ok();
+            }
         }
     }
 }
diff --git a/gix/src/clone/fetch/mod.rs b/gix/src/clone/fetch/mod.rs
@@ -318,6 +318,7 @@ impl PrepareFetch {
             crate::clone::PrepareCheckout {
                 repo: repo.into(),
                 ref_name: self.ref_name.clone(),
+                destination_was_empty: self.destination_was_empty,
             },
             fetch_outcome,
         ))
diff --git a/gix/src/clone/mod.rs b/gix/src/clone/mod.rs
@@ -42,6 +42,9 @@ pub struct PrepareFetch {
     /// The name of the reference to fetch. If `None`, the reference pointed to by `HEAD` will be checked out.
     #[cfg_attr(not(feature = "blocking-network-client"), allow(dead_code))]
     ref_name: Option<gix_ref::PartialName>,
+    /// `true` iff the destination directory was empty (or did not exist) when this handle was created.
+    /// When `false`, drop will avoid removing pre-existing user files and only clean up the `.git` we created.
+    destination_was_empty: bool,
 }
 
 /// The error returned by [`PrepareFetch::new()`].
@@ -102,7 +105,17 @@ impl PrepareFetch {
         mut create_opts: crate::create::Options,
         open_opts: crate::open::Options,
     ) -> Result<Self, Error> {
-        create_opts.destination_must_be_empty = true;
+        if create_opts.destination_must_be_empty.is_none() {
+            create_opts.destination_must_be_empty = Some(true);
+        }
+
+        // Capture this before init_opts creates `.git`, otherwise the check below would see our own files.
+        let destination_was_empty = match std::fs::read_dir(path) {
+            Ok(mut entries) => entries.next().is_none(),
+            // Non-existent (or unreadable) — init_opts will create the directory.
+            Err(_) => true,
+        };
+
         let mut repo = crate::ThreadSafeRepository::init_opts(path, kind, create_opts, open_opts)?.to_thread_local();
         url.canonicalize(repo.options.current_dir_or_empty())
             .map_err(|err| Error::CanonicalizeUrl {
@@ -122,6 +135,7 @@ impl PrepareFetch {
             configure_connection: None,
             shallow: remote::fetch::Shallow::NoChange,
             ref_name: None,
+            destination_was_empty,
         })
     }
 }
@@ -136,6 +150,9 @@ pub struct PrepareCheckout {
     pub(self) repo: Option<crate::Repository>,
     /// The name of the reference to check out. If `None`, the reference pointed to by `HEAD` will be checked out.
     pub(self) ref_name: Option<gix_ref::PartialName>,
+    /// `true` iff the destination directory was empty (or did not exist) when the parent [`PrepareFetch`] was created.
+    /// When `false`, drop must avoid removing pre-existing user files and only clean up the `.git` we created.
+    pub(self) destination_was_empty: bool,
 }
 
 // This module encapsulates functionality that works with both feature toggles. Can be combined with `fetch`
diff --git a/gix/src/create.rs b/gix/src/create.rs
@@ -110,10 +110,17 @@ fn create_dir(p: &Path) -> Result<(), Error> {
 /// Options for use in [`into()`];
 #[derive(Copy, Clone, Default)]
 pub struct Options {
-    /// If true, and the kind of repository to create has a worktree, then the destination directory must be empty.
+    /// Control whether the destination directory must be empty when creating a repository with a worktree.
     ///
-    /// By default repos with worktree can be initialized into a non-empty repository as long as there is no `.git` directory.
-    pub destination_must_be_empty: bool,
+    /// - `None` (default): worktree repos may be initialized into a non-empty directory as long as no `.git`
+    ///   directory is present. [`crate::clone::PrepareFetch::new`] interprets `None` as `Some(true)` to preserve
+    ///   the historical strict-by-default behavior for clones.
+    /// - `Some(true)`: require an empty destination directory.
+    /// - `Some(false)`: explicitly allow initialization into a non-empty destination directory (still requires
+    ///   that no `.git` directory is present).
+    ///
+    /// Bare repositories always require an empty destination, regardless of this option.
+    pub destination_must_be_empty: Option<bool>,
     /// If set, use these filesystem capabilities to populate the respective git-config fields.
     /// If `None`, the directory will be probed.
     pub fs_capabilities: Option<gix_fs::Capabilities>,
@@ -135,7 +142,7 @@ pub fn into(
     let mut dot_git = directory.into();
     let bare = matches!(kind, Kind::Bare);
 
-    if bare || destination_must_be_empty {
+    if bare || destination_must_be_empty.unwrap_or(false) {
         let num_entries_in_dot_git = fs::read_dir(&dot_git)
             .or_else(|err| {
                 if err.kind() == std::io::ErrorKind::NotFound {
diff --git a/gix/tests/gix/clone.rs b/gix/tests/gix/clone.rs
@@ -585,6 +585,71 @@ mod blocking_io {
         Ok(())
     }
 
+    #[test]
+    fn fetch_and_checkout_into_non_empty_directory() -> crate::Result {
+        let tmp = gix_testtools::tempfile::TempDir::new()?;
+        let existing_path = tmp.path().join("existing.txt");
+        let existing_content = b"I was here before you";
+        std::fs::write(&existing_path, existing_content)?;
+
+        let mut prepare = gix::clone::PrepareFetch::new(
+            remote::repo("base").path(),
+            tmp.path(),
+            gix::create::Kind::WithWorktree,
+            gix::create::Options {
+                destination_must_be_empty: Some(false),
+                ..Default::default()
+            },
+            restricted(),
+        )?;
+        let (mut checkout, _out) =
+            prepare.fetch_then_checkout(gix::progress::Discard, &std::sync::atomic::AtomicBool::default())?;
+        let (repo, _) = checkout.main_worktree(gix::progress::Discard, &std::sync::atomic::AtomicBool::default())?;
+
+        let index = repo.index()?;
+        assert_eq!(index.entries().len(), 1, "All entries are known as per HEAD tree");
+        assure_index_entries_on_disk(&index, repo.workdir().expect("non-bare"));
+
+        assert_eq!(std::fs::read(&existing_path)?, existing_content);
+        Ok(())
+    }
+
+    #[test]
+    fn drop_after_failed_fetch_into_non_empty_directory_preserves_pre_existing_files() -> crate::Result {
+        let tmp = gix_testtools::tempfile::TempDir::new()?;
+        let existing_path = tmp.path().join("existing.txt");
+        let existing_content = b"I was here before you";
+        std::fs::write(&existing_path, existing_content)?;
+
+        let mut prepare = gix::clone::PrepareFetch::new(
+            remote::repo("base").path(),
+            tmp.path(),
+            gix::create::Kind::WithWorktree,
+            gix::create::Options {
+                destination_must_be_empty: Some(false),
+                ..Default::default()
+            },
+            restricted(),
+        )?
+        .with_ref_name(Some("does-not-exist"))?;
+
+        prepare
+            .fetch_then_checkout(gix::progress::Discard, &AtomicBool::default())
+            .expect_err("non-existing ref must fail");
+        drop(prepare);
+
+        assert_eq!(
+            std::fs::read(&existing_path)?,
+            existing_content,
+            "pre-existing user files must survive a failed clone+drop"
+        );
+        assert!(
+            !tmp.path().join(".git").exists(),
+            "only the .git directory we created should have been cleaned up"
+        );
+        Ok(())
+    }
+
     #[test]
     fn fetch_and_checkout_specific_ref() -> crate::Result {
         let tmp = gix_testtools::tempfile::TempDir::new()?;
@@ -832,6 +897,26 @@ fn clone_and_destination_must_be_empty() -> crate::Result {
     Ok(())
 }
 
+#[test]
+fn clone_with_worktree_and_destination_must_be_empty() -> crate::Result {
+    let tmp = gix_testtools::tempfile::TempDir::new()?;
+    std::fs::write(tmp.path().join("file"), b"hello")?;
+    match gix::clone::PrepareFetch::new(
+        remote::repo("base").path(),
+        tmp.path(),
+        gix::create::Kind::WithWorktree,
+        Default::default(),
+        restricted(),
+    ) {
+        Ok(_) => unreachable!("this should fail as the directory isn't empty"),
+        Err(err) => assert!(
+            err.to_string()
+                .starts_with("Refusing to initialize the non-empty directory as ")
+        ),
+    }
+    Ok(())
+}
+
 #[test]
 fn clone_bare_into_empty_directory_and_early_drop() -> crate::Result {
     let tmp = gix_testtools::tempfile::TempDir::new()?;
diff --git a/gix/tests/gix/init.rs b/gix/tests/gix/init.rs
@@ -172,7 +172,7 @@ mod non_bare {
             tmp.path(),
             gix::create::Kind::WithWorktree,
             gix::create::Options {
-                destination_must_be_empty: true,
+                destination_must_be_empty: Some(true),
                 ..Default::default()
             },
             gix::open::Options::isolated(),

Original file line number	Diff line number	Diff line change
`@@ -73,7 +73,12 @@ impl PrepareFetch {`
`73`	`73`	`impl Drop for PrepareFetch {`
`74`	`74`	`fn drop(&mut self) {`
`75`	`75`	`if let Some(repo) = self.repo.take() {`
`76`		`- std::fs::remove_dir_all(repo.workdir().unwrap_or_else(\|\| repo.path())).ok();`
	`76`	`+ if self.destination_was_empty {`
	`77`	`+ std::fs::remove_dir_all(repo.workdir().unwrap_or_else(\|\| repo.path())).ok();`
	`78`	`+ } else {`
	`79`	+ // The destination held pre-existing user files; only remove the `.git` we created.
	`80`	`+ std::fs::remove_dir_all(repo.path()).ok();`
	`81`	`+ }`
`77`	`82`	`}`
`78`	`83`	`}`
`79`	`84`	`}`
Original file line number	Diff line number	Diff line change
`@@ -171,7 +171,12 @@ impl PrepareCheckout {`
`171`	`171`	`impl Drop for PrepareCheckout {`
`172`	`172`	`fn drop(&mut self) {`
`173`	`173`	`if let Some(repo) = self.repo.take() {`
`174`		`- std::fs::remove_dir_all(repo.workdir().unwrap_or_else(\|\| repo.path())).ok();`
	`174`	`+ if self.destination_was_empty {`
	`175`	`+ std::fs::remove_dir_all(repo.workdir().unwrap_or_else(\|\| repo.path())).ok();`
	`176`	`+ } else {`
	`177`	+ // The destination held pre-existing user files; only remove the `.git` we created.
	`178`	`+ std::fs::remove_dir_all(repo.path()).ok();`
	`179`	`+ }`
`175`	`180`	`}`
`176`	`181`	`}`
`177`	`182`	`}`