From 9db21601b61601c01cd2419543e2c461a7dd568d Mon Sep 17 00:00:00 2001
From: Sebastian Thiel <sebastian.thiel@icloud.com>
Date: Sun, 12 Jan 2025 11:02:12 +0100
Subject: [PATCH] doc: make really clear that `Repository::worktrees()` lists
 linked worktrees.

Excluding the main worktree which isn't always present.
---
 gix/src/repository/worktree.rs |  9 +++++++--
 gix/tests/gix/submodule.rs     | 23 +++++++++++++++++++++++
 2 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/gix/src/repository/worktree.rs b/gix/src/repository/worktree.rs
index f5ed8483496..09ff3910886 100644
--- a/gix/src/repository/worktree.rs
+++ b/gix/src/repository/worktree.rs
@@ -2,12 +2,17 @@ use crate::{worktree, Worktree};
 
 /// Interact with individual worktrees and their information.
 impl crate::Repository {
-    /// Return a list of all _linked_ worktrees sorted by private git dir path as a lightweight proxy.
+    /// Return a list of all **linked** worktrees sorted by private git dir path as a lightweight proxy.
+    ///
+    /// This means the number is `0` even if there is the main worktree, as it is not counted as linked worktree.
+    /// This also means it will be `1` if there is one linked worktree next to the main worktree.
+    /// It's worth noting that a *bare* repository may have one or more linked worktrees, but has no *main* worktree,
+    /// which is the reason why the *possibly* available main worktree isn't listed here.
     ///
     /// Note that these need additional processing to become usable, but provide a first glimpse a typical worktree information.
     pub fn worktrees(&self) -> std::io::Result<Vec<worktree::Proxy<'_>>> {
         let mut res = Vec::new();
-        let iter = match std::fs::read_dir(self.common_dir().join("worktrees")) {
+        let iter = match std::fs::read_dir(dbg!(self.common_dir()).join("worktrees")) {
             Ok(iter) => iter,
             Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(res),
             Err(err) => return Err(err),
diff --git a/gix/tests/gix/submodule.rs b/gix/tests/gix/submodule.rs
index 895c16f4a17..1f6536fc715 100644
--- a/gix/tests/gix/submodule.rs
+++ b/gix/tests/gix/submodule.rs
@@ -358,6 +358,29 @@ mod open {
             wd.join("this").is_file(),
             "The submodule itself has the file, so it should be in the worktree"
         );
+
+        assert_eq!(sm_repo.worktrees()?.len(), 1, "only a single linked worktree");
+        Ok(())
+    }
+
+    #[test]
+    fn list_submodule_worktrees() -> crate::Result {
+        let sm_repo = named_subrepo_opts(
+            "make_submodule_with_worktree.sh",
+            "submodule-with-extra-worktree-host/m1",
+            gix::open::Options::isolated(),
+        )?;
+        let wd = sm_repo.work_dir().expect("workdir is present");
+        assert!(
+            sm_repo.rev_parse_single(":this").is_ok(),
+            "the file is in the submodule"
+        );
+        assert!(
+            wd.join("this").is_file(),
+            "The submodule itself has the file, so it should be in the worktree"
+        );
+
+        assert_eq!(sm_repo.worktrees()?.len(), 1, "only a single linked worktree");
         Ok(())
     }