Represent relative paths using a dedicated, separator-agnostic type (#38744)

Closes https://github.com/zed-industries/zed/issues/38690
Closes #37353

### Background

On Windows, paths are normally separated by `\`, unlike mac and linux
where they are separated by `/`. When editing code in a project that
uses a different path style than your local system (e.g. remoting from
Windows to Linux, using WSL, and collaboration between windows and unix
users), the correct separator for a path may differ from the "native"
separator.

Previously, to work around this, Zed converted paths' separators in
numerous places. This was applied to both absolute and relative paths,
leading to incorrect conversions in some cases.

### Solution

Many code paths in Zed use paths that are *relative* to either a
worktree root or a git repository. This PR introduces a dedicated type
for these paths called `RelPath`, which stores the path in the same way
regardless of host platform, and offers `Path`-like manipulation APIs.
RelPath supports *displaying* the path using either separator, so that
we can display paths in a style that is determined at runtime based on
the current project.

The representation of absolute paths is left untouched, for now.
Absolute paths are different from relative paths because (except in
contexts where we know that the path refers to the local filesystem)
they should generally be treated as opaque strings. Currently we use a
mix of types for these paths (std::path::Path, String, SanitizedPath).

Release Notes:

- N/A

---------

Co-authored-by: Cole Miller <cole@zed.dev>
Co-authored-by: Piotr Osiewicz <24362066+osiewicz@users.noreply.github.com>
Co-authored-by: Peter Tripp <petertripp@gmail.com>
Co-authored-by: Smit Barmase <heysmitbarmase@gmail.com>
Co-authored-by: Lukas Wirth <me@lukaswirth.dev>

crates/agent2/src/agent.rs

@@ -27,6 +27,7 @@ use std::path::{Path, PathBuf};
 use std::rc::Rc;
 use std::sync::Arc;
 use util::ResultExt;
+use util::rel_path::RelPath;
 
 const RULES_FILE_NAMES: [&str; 9] = [
     ".rules",
@@ -434,7 +435,7 @@ impl NativeAgent {
         cx: &mut App,
     ) -> Task<(WorktreeContext, Option<RulesLoadingError>)> {
         let tree = worktree.read(cx);
-        let root_name = tree.root_name().into();
+        let root_name = tree.root_name_str().into();
         let abs_path = tree.abs_path();
 
         let mut context = WorktreeContext {
@@ -474,7 +475,7 @@ impl NativeAgent {
             .into_iter()
             .filter_map(|name| {
                 worktree
-                    .entry_for_path(name)
+                    .entry_for_path(RelPath::new(name).unwrap())
                     .filter(|entry| entry.is_file())
                     .map(|entry| entry.path.clone())
             })
@@ -558,7 +559,7 @@ impl NativeAgent {
                 if items.iter().any(|(path, _, _)| {
                     RULES_FILE_NAMES
                         .iter()
-                        .any(|name| path.as_ref() == Path::new(name))
+                        .any(|name| path.as_ref() == RelPath::new(name).unwrap())
                 }) {
                     self.project_context_needs_refresh.send(()).ok();
                 }
@@ -1208,7 +1209,7 @@ mod tests {
     use language_model::fake_provider::FakeLanguageModel;
     use serde_json::json;
     use settings::SettingsStore;
-    use util::path;
+    use util::{path, rel_path::rel_path};
 
     #[gpui::test]
     async fn test_maintaining_project_context(cx: &mut TestAppContext) {
@@ -1258,14 +1259,17 @@ mod tests {
         fs.insert_file("/a/.rules", Vec::new()).await;
         cx.run_until_parked();
         agent.read_with(cx, |agent, cx| {
-            let rules_entry = worktree.read(cx).entry_for_path(".rules").unwrap();
+            let rules_entry = worktree
+                .read(cx)
+                .entry_for_path(rel_path(".rules"))
+                .unwrap();
             assert_eq!(
                 agent.project_context.read(cx).worktrees,
                 vec![WorktreeContext {
                     root_name: "a".into(),
                     abs_path: Path::new("/a").into(),
                     rules_file: Some(RulesFileContext {
-                        path_in_worktree: Path::new(".rules").into(),
+                        path_in_worktree: rel_path(".rules").into(),
                         text: "".into(),
                         project_entry_id: rules_entry.id.to_usize()
                     })

crates/agent2/src/db.rs

@@ -422,17 +422,15 @@ mod tests {
     use agent::MessageSegment;
     use agent::context::LoadedContext;
     use client::Client;
-    use fs::FakeFs;
+    use fs::{FakeFs, Fs};
     use gpui::AppContext;
     use gpui::TestAppContext;
     use http_client::FakeHttpClient;
     use language_model::Role;
     use project::Project;
-    use serde_json::json;
     use settings::SettingsStore;
-    use util::test::TempTree;
 
-    fn init_test(cx: &mut TestAppContext) {
+    fn init_test(fs: Arc<dyn Fs>, cx: &mut TestAppContext) {
         env_logger::try_init().ok();
         cx.update(|cx| {
             let settings_store = SettingsStore::test(cx);
@@ -443,7 +441,7 @@ mod tests {
             let http_client = FakeHttpClient::with_404_response();
             let clock = Arc::new(clock::FakeSystemClock::new());
             let client = Client::new(clock, http_client, cx);
-            agent::init(cx);
+            agent::init(fs, cx);
             agent_settings::init(cx);
             language_model::init(client, cx);
         });
@@ -451,10 +449,8 @@ mod tests {
 
     #[gpui::test]
     async fn test_retrieving_old_thread(cx: &mut TestAppContext) {
-        let tree = TempTree::new(json!({}));
-        util::paths::set_home_dir(tree.path().into());
-        init_test(cx);
         let fs = FakeFs::new(cx.executor());
+        init_test(fs.clone(), cx);
         let project = Project::test(fs, [], cx).await;
 
         // Save a thread using the old agent.

crates/agent2/src/thread.rs

@@ -879,27 +879,11 @@ impl Thread {
             .map(|worktree| Self::worktree_snapshot(worktree, git_store.clone(), cx))
             .collect();
 
-        cx.spawn(async move |_, cx| {
+        cx.spawn(async move |_, _| {
             let worktree_snapshots = futures::future::join_all(worktree_snapshots).await;
 
-            let mut unsaved_buffers = Vec::new();
-            cx.update(|app_cx| {
-                let buffer_store = project.read(app_cx).buffer_store();
-                for buffer_handle in buffer_store.read(app_cx).buffers() {
-                    let buffer = buffer_handle.read(app_cx);
-                    if buffer.is_dirty()
-                        && let Some(file) = buffer.file()
-                    {
-                        let path = file.path().to_string_lossy().to_string();
-                        unsaved_buffers.push(path);
-                    }
-                }
-            })
-            .ok();
-
             Arc::new(ProjectSnapshot {
                 worktree_snapshots,
-                unsaved_buffer_paths: unsaved_buffers,
                 timestamp: Utc::now(),
             })
         })

crates/agent2/src/tools/copy_path_tool.rs

@@ -84,9 +84,7 @@ impl AgentTool for CopyPathTool {
                 .and_then(|project_path| project.entry_for_path(&project_path, cx))
             {
                 Some(entity) => match project.find_project_path(&input.destination_path, cx) {
-                    Some(project_path) => {
-                        project.copy_entry(entity.id, None, project_path.path, cx)
-                    }
+                    Some(project_path) => project.copy_entry(entity.id, project_path, cx),
                     None => Task::ready(Err(anyhow!(
                         "Destination path {} was outside the project.",
                         input.destination_path

crates/agent2/src/tools/diagnostics_tool.rs

@@ -6,7 +6,7 @@ use language::{DiagnosticSeverity, OffsetRangeExt};
 use project::Project;
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
-use std::{fmt::Write, path::Path, sync::Arc};
+use std::{fmt::Write, sync::Arc};
 use ui::SharedString;
 use util::markdown::MarkdownInlineCode;
 
@@ -147,9 +147,7 @@ impl AgentTool for DiagnosticsTool {
                         has_diagnostics = true;
                         output.push_str(&format!(
                             "{}: {} error(s), {} warning(s)\n",
-                            Path::new(worktree.read(cx).root_name())
-                                .join(project_path.path)
-                                .display(),
+                            worktree.read(cx).absolutize(&project_path.path).display(),
                             summary.error_count,
                             summary.warning_count
                         ));

crates/agent2/src/tools/edit_file_tool.rs

@@ -17,10 +17,12 @@ use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use settings::Settings;
 use smol::stream::StreamExt as _;
+use std::ffi::OsStr;
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
 use ui::SharedString;
 use util::ResultExt;
+use util::rel_path::RelPath;
 
 const DEFAULT_UI_TEXT: &str = "Editing file";
 
@@ -148,12 +150,11 @@ impl EditFileTool {
 
         // If any path component matches the local settings folder, then this could affect
         // the editor in ways beyond the project source, so prompt.
-        let local_settings_folder = paths::local_settings_folder_relative_path();
+        let local_settings_folder = paths::local_settings_folder_name();
         let path = Path::new(&input.path);
-        if path
-            .components()
-            .any(|component| component.as_os_str() == local_settings_folder.as_os_str())
-        {
+        if path.components().any(|component| {
+            component.as_os_str() == <_ as AsRef<OsStr>>::as_ref(&local_settings_folder)
+        }) {
             return event_stream.authorize(
                 format!("{} (local settings)", input.display_description),
                 cx,
@@ -162,6 +163,7 @@ impl EditFileTool {
 
         // It's also possible that the global config dir is configured to be inside the project,
         // so check for that edge case too.
+        // TODO this is broken when remoting
         if let Ok(canonical_path) = std::fs::canonicalize(&input.path)
             && canonical_path.starts_with(paths::config_dir())
         {
@@ -216,9 +218,7 @@ impl AgentTool for EditFileTool {
                         .read(cx)
                         .short_full_path_for_project_path(&project_path, cx)
                 })
-                .unwrap_or(Path::new(&input.path).into())
-                .to_string_lossy()
-                .to_string()
+                .unwrap_or(input.path.to_string_lossy().to_string())
                 .into(),
             Err(raw_input) => {
                 if let Some(input) =
@@ -235,9 +235,7 @@ impl AgentTool for EditFileTool {
                                     .read(cx)
                                     .short_full_path_for_project_path(&project_path, cx)
                             })
-                            .unwrap_or(Path::new(&input.path).into())
-                            .to_string_lossy()
-                            .to_string()
+                            .unwrap_or(input.path)
                             .into();
                     }
 
@@ -478,7 +476,7 @@ impl AgentTool for EditFileTool {
     ) -> Result<()> {
         event_stream.update_diff(cx.new(|cx| {
             Diff::finalized(
-                output.input_path,
+                output.input_path.to_string_lossy().to_string(),
                 Some(output.old_text.to_string()),
                 output.new_text,
                 self.language_registry.clone(),
@@ -542,10 +540,12 @@ fn resolve_path(
             let file_name = input
                 .path
                 .file_name()
+                .and_then(|file_name| file_name.to_str())
+                .and_then(|file_name| RelPath::new(file_name).ok())
                 .context("Can't create file: invalid filename")?;
 
             let new_file_path = parent_project_path.map(|parent| ProjectPath {
-                path: Arc::from(parent.path.join(file_name)),
+                path: parent.path.join(file_name),
                 ..parent
             });
 
@@ -690,13 +690,10 @@ mod tests {
         cx.update(|cx| resolve_path(&input, project, cx))
     }
 
+    #[track_caller]
     fn assert_resolved_path_eq(path: anyhow::Result<ProjectPath>, expected: &str) {
-        let actual = path
-            .expect("Should return valid path")
-            .path
-            .to_str()
-            .unwrap()
-            .replace("\\", "/"); // Naive Windows paths normalization
+        let actual = path.expect("Should return valid path").path;
+        let actual = actual.as_str();
         assert_eq!(actual, expected);
     }
 
@@ -1408,8 +1405,8 @@ mod tests {
             // Parent directory references - find_project_path resolves these
             (
                 "project/../other",
-                false,
-                "Path with .. is resolved by find_project_path",
+                true,
+                "Path with .. that goes outside of root directory",
             ),
             (
                 "project/./src/file.rs",
@@ -1437,16 +1434,18 @@ mod tests {
                 )
             });
 
+            cx.run_until_parked();
+
             if should_confirm {
                 stream_rx.expect_authorization().await;
             } else {
-                auth.await.unwrap();
                 assert!(
                     stream_rx.try_next().is_err(),
                     "Failed for case: {} - path: {} - expected no confirmation but got one",
                     description,
                     path
                 );
+                auth.await.unwrap();
             }
         }
     }

crates/agent2/src/tools/find_path_tool.rs

@@ -156,10 +156,14 @@ impl AgentTool for FindPathTool {
 }
 
 fn search_paths(glob: &str, project: Entity<Project>, cx: &mut App) -> Task<Result<Vec<PathBuf>>> {
-    let path_matcher = match PathMatcher::new([
-        // Sometimes models try to search for "". In this case, return all paths in the project.
-        if glob.is_empty() { "*" } else { glob },
-    ]) {
+    let path_style = project.read(cx).path_style(cx);
+    let path_matcher = match PathMatcher::new(
+        [
+            // Sometimes models try to search for "". In this case, return all paths in the project.
+            if glob.is_empty() { "*" } else { glob },
+        ],
+        path_style,
+    ) {
         Ok(matcher) => matcher,
         Err(err) => return Task::ready(Err(anyhow!("Invalid glob: {err}"))),
     };
@@ -173,9 +177,8 @@ fn search_paths(glob: &str, project: Entity<Project>, cx: &mut App) -> Task<Resu
         let mut results = Vec::new();
         for snapshot in snapshots {
             for entry in snapshot.entries(false, 0) {
-                let root_name = PathBuf::from(snapshot.root_name());
-                if path_matcher.is_match(root_name.join(&entry.path)) {
-                    results.push(snapshot.abs_path().join(entry.path.as_ref()));
+                if path_matcher.is_match(snapshot.root_name().join(&entry.path).as_std_path()) {
+                    results.push(snapshot.absolutize(&entry.path));
                 }
             }
         }

crates/agent2/src/tools/grep_tool.rs

@@ -110,12 +110,15 @@ impl AgentTool for GrepTool {
         const CONTEXT_LINES: u32 = 2;
         const MAX_ANCESTOR_LINES: u32 = 10;
 
+        let path_style = self.project.read(cx).path_style(cx);
+
         let include_matcher = match PathMatcher::new(
             input
                 .include_pattern
                 .as_ref()
                 .into_iter()
                 .collect::<Vec<_>>(),
+            path_style,
         ) {
             Ok(matcher) => matcher,
             Err(error) => {
@@ -132,7 +135,7 @@ impl AgentTool for GrepTool {
                 .iter()
                 .chain(global_settings.private_files.sources().iter());
 
-            match PathMatcher::new(exclude_patterns) {
+            match PathMatcher::new(exclude_patterns, path_style) {
                 Ok(matcher) => matcher,
                 Err(error) => {
                     return Task::ready(Err(anyhow!("invalid exclude pattern: {error}")));

crates/agent2/src/tools/list_directory_tool.rs

@@ -2,12 +2,12 @@ use crate::{AgentTool, ToolCallEventStream};
 use agent_client_protocol::ToolKind;
 use anyhow::{Result, anyhow};
 use gpui::{App, Entity, SharedString, Task};
-use project::{Project, WorktreeSettings};
+use project::{Project, ProjectPath, WorktreeSettings};
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use settings::Settings;
 use std::fmt::Write;
-use std::{path::Path, sync::Arc};
+use std::sync::Arc;
 use util::markdown::MarkdownInlineCode;
 
 /// Lists files and directories in a given path. Prefer the `grep` or `find_path` tools when searching the codebase.
@@ -86,13 +86,13 @@ impl AgentTool for ListDirectoryTool {
                 .read(cx)
                 .worktrees(cx)
                 .filter_map(|worktree| {
-                    worktree.read(cx).root_entry().and_then(|entry| {
-                        if entry.is_dir() {
-                            entry.path.to_str()
-                        } else {
-                            None
-                        }
-                    })
+                    let worktree = worktree.read(cx);
+                    let root_entry = worktree.root_entry()?;
+                    if root_entry.is_dir() {
+                        Some(root_entry.path.display(worktree.path_style()))
+                    } else {
+                        None
+                    }
                 })
                 .collect::<Vec<_>>()
                 .join("\n");
@@ -143,7 +143,7 @@ impl AgentTool for ListDirectoryTool {
         }
 
         let worktree_snapshot = worktree.read(cx).snapshot();
-        let worktree_root_name = worktree.read(cx).root_name().to_string();
+        let worktree_root_name = worktree.read(cx).root_name();
 
         let Some(entry) = worktree_snapshot.entry_for_path(&project_path.path) else {
             return Task::ready(Err(anyhow!("Path not found: {}", input.path)));
@@ -165,25 +165,17 @@ impl AgentTool for ListDirectoryTool {
                 continue;
             }
 
-            if self
-                .project
-                .read(cx)
-                .find_project_path(&entry.path, cx)
-                .map(|project_path| {
-                    let worktree_settings = WorktreeSettings::get(Some((&project_path).into()), cx);
-
-                    worktree_settings.is_path_excluded(&project_path.path)
-                        || worktree_settings.is_path_private(&project_path.path)
-                })
-                .unwrap_or(false)
+            let project_path: ProjectPath = (worktree_snapshot.id(), entry.path.clone()).into();
+            if worktree_settings.is_path_excluded(&project_path.path)
+                || worktree_settings.is_path_private(&project_path.path)
             {
                 continue;
             }
 
-            let full_path = Path::new(&worktree_root_name)
+            let full_path = worktree_root_name
                 .join(&entry.path)
-                .display()
-                .to_string();
+                .display(worktree_snapshot.path_style())
+                .into_owned();
             if entry.is_dir() {
                 folders.push(full_path);
             } else {

crates/agent2/src/tools/move_path_tool.rs

@@ -98,7 +98,7 @@ impl AgentTool for MovePathTool {
                 .and_then(|project_path| project.entry_for_path(&project_path, cx))
             {
                 Some(entity) => match project.find_project_path(&input.destination_path, cx) {
-                    Some(project_path) => project.rename_entry(entity.id, project_path.path, cx),
+                    Some(project_path) => project.rename_entry(entity.id, project_path, cx),
                     None => Task::ready(Err(anyhow!(
                         "Destination path {} was outside the project.",
                         input.destination_path

crates/agent2/src/tools/read_file_tool.rs

@@ -82,12 +82,12 @@ impl AgentTool for ReadFileTool {
         {
             match (input.start_line, input.end_line) {
                 (Some(start), Some(end)) => {
-                    format!("Read file `{}` (lines {}-{})", path.display(), start, end,)
+                    format!("Read file `{path}` (lines {}-{})", start, end,)
                 }
                 (Some(start), None) => {
-                    format!("Read file `{}` (from line {})", path.display(), start)
+                    format!("Read file `{path}` (from line {})", start)
                 }
-                _ => format!("Read file `{}`", path.display()),
+                _ => format!("Read file `{path}`"),
             }
             .into()
         } else {