Portability: exec bits, symlinks and path names on macOS and Windows c863c7a7a2d1

//! What the file system of the working copy can represent (spec §7.7),

//! and which paths of a state it cannot.

//!

//! Executable bits and symbolic links exist on Unix only; elsewhere a

//! snapshot keeps the recorded executable bit and reads a symlink written

//! out as a plain file back as the symlink. macOS and Windows file systems

//! ignore case by default and Windows forbids some names, so paths that

//! differ only in case or use such names are reported before they are

//! written.

use std::collections::BTreeMap;

/// Capabilities of the working copy's file system.

#[derive(Clone, Copy, Debug, PartialEq, Eq)]

pub struct Platform {

    pub exec_bits: bool,

    pub symlinks: bool,

    pub case_insensitive: bool,

    /// Windows' name rules: reserved device names, `<>:"\|?*`, trailing dots and spaces.

    pub windows_names: bool,

}

impl Platform {

    /// The platform oxy runs on, with its default file system.

    pub fn current() -> Platform {

        Platform {

            exec_bits: cfg!(unix),

            symlinks: cfg!(unix),

            case_insensitive: cfg!(any(target_os = "macos", target_os = "windows")),

            windows_names: cfg!(target_os = "windows"),

        }

    }

    pub fn windows() -> Platform {

        Platform {

            exec_bits: false,

            symlinks: false,

            case_insensitive: true,

            windows_names: true,

        }

    }

    pub fn macos() -> Platform {

        Platform {

            exec_bits: true,

            symlinks: true,

            case_insensitive: true,

            windows_names: false,

        }

    }

    /// Problems this platform would have with these paths.

    pub fn problems<'a>(&self, paths: impl IntoIterator<Item = &'a str>) -> Vec<String> {

        let paths: Vec<&str> = paths.into_iter().collect();

        let mut out = Vec::new();

        if self.case_insensitive {

            out.extend(

                case_collisions(&paths).into_iter().map(|(a, b)| {

                    format!("{a} and {b} differ only in case; one will hide the other")

                }),

            );

        }

        if self.windows_names {

            out.extend(

                paths

                    .iter()

                    .filter_map(|p| windows_name_problem(p).map(|why| format!("{p}: {why}"))),

            );

        }

        out

    }

}

/// Pairs of paths equal but for case (including a directory's case).

pub fn case_collisions(paths: &[&str]) -> Vec<(String, String)> {

    let mut seen: BTreeMap<String, &str> = BTreeMap::new();

    let mut out = Vec::new();

    // Every prefix counts: `Docs/a` and `docs/b` put two directories in one place.

    let mut prefixes: Vec<&str> = Vec::new();

    for p in paths {

        let mut end = 0;

        for part in p.split('/') {

            end += part.len();

            prefixes.push(&p[..end]);

            end += 1;

        }

    }

    prefixes.sort();

    prefixes.dedup();

    for p in prefixes {

        let key = p.to_lowercase();

        match seen.get(&key) {

            Some(first) if *first != p => out.push((first.to_string(), p.to_string())),

            Some(_) => {}

            None => {

                seen.insert(key, p);

            }

        }

    }

    out

}

/// Why Windows would refuse a path, if it would.

pub fn windows_name_problem(path: &str) -> Option<&'static str> {

    const RESERVED: &[&str] = &[

        "CON", "PRN", "AUX", "NUL", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8",

        "COM9", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9",

    ];

    for part in path.split('/') {

        if part

            .chars()

            .any(|c| matches!(c, '<' | '>' | ':' | '"' | '\\' | '|' | '?' | '*') || (c as u32) < 32)

        {

            return Some("contains a character Windows does not allow in names");

        }

        if part.ends_with('.') || part.ends_with(' ') {

            return Some("a name ending in a dot or space cannot be created on Windows");

        }

        let stem = part.split('.').next().unwrap_or("").to_ascii_uppercase();

        if RESERVED.contains(&stem.as_str()) {

            return Some("a reserved device name on Windows");

        }

    }

    None

}

#[cfg(test)]

mod tests {

    use super::*;

    #[test]

    fn collisions_and_names() {

        assert_eq!(

            case_collisions(&["README.md", "readme.md", "src/a.rs"]),

            vec![("README.md".into(), "readme.md".into())]

        );

        assert_eq!(

            case_collisions(&["Docs/a", "docs/b"]),

            vec![("Docs".into(), "docs".into())]

        );

        assert!(case_collisions(&["a/b", "a/c", "b"]).is_empty());

        assert!(windows_name_problem("src/con.rs").is_some());

        assert!(windows_name_problem("notes/a:b.txt").is_some());

        assert!(windows_name_problem("trailing./x").is_some());

        assert!(windows_name_problem("src/console.rs").is_none());

        let w = Platform::windows();

        assert_eq!(w.problems(["A.txt", "a.txt", "aux.c"]).len(), 2);

        assert!(Platform {

            exec_bits: true,

            symlinks: true,

            case_insensitive: false,

            windows_names: false

        }

        .problems(["A", "a"])

        .is_empty());

    }

}

pub mod portable;

        // Paths this file system cannot hold side by side (spec §7.7).

        report.notes.extend(

            self.platform

                .problems(target.files.keys().map(String::as_str)),

        );

                        c.kind == NodeKind::File

                            && c.content == *on_disk

                            && (!self.platform.exec_bits || c.exec == f.mode.exec)

                            c.kind == NodeKind::File

                                && c.content == bytes

                                && (!self.platform.exec_bits || c.exec == f.mode.exec)

        self.doctor_portability(&mut rep);

    /// Paths of the current bookmark that another platform's file system

    /// cannot check out as they are (spec §7.7).

    fn doctor_portability(&self, rep: &mut DoctorReport) {

        let Ok(heads) = self.bookmark_heads() else {

            return;

        };

        let Ok(state) = self.load_state(&heads) else {

            return;

        };

        let view = state.tree().view();

        let paths: Vec<&str> = view.entries.keys().map(String::as_str).collect();

        let mut problems: Vec<String> =

            crate::portable::Platform::windows().problems(paths.iter().copied());

        problems.sort();

        problems.dedup();

        if problems.is_empty() {

            rep.push(

                "portability",

                Health::Ok,

                format!(

                    "every path of {} checks out on Linux, macOS and Windows",

                    self.config.bookmark

                ),

                None,

            );

            return;

        }

        let shown: Vec<&String> = problems.iter().take(5).collect();

        rep.push(

            "portability",

            Health::Warn,

            format!(

                "{} path problem{} on case-insensitive or Windows file systems: {}{}",

                problems.len(),

                if problems.len() == 1 { "" } else { "s" },

                shown.iter().map(|s| s.as_str()).collect::<Vec<_>>().join("; "),

                if problems.len() > 5 { "; …" } else { "" }

            ),

            Some("rename the paths so they differ by more than case and avoid Windows' reserved names and characters".into()),

        );

    }

    /// What the working copy's file system can represent (spec §7.7).

    platform: crate::portable::Platform,

            platform: crate::portable::Platform::current(),

            platform: crate::portable::Platform::current(),

                    platform: crate::portable::Platform::current(),

                    platform: crate::portable::Platform::current(),

    /// Act as if the working copy were on another platform's file system

    /// (tests of Windows and macOS behaviour on any host).

    pub fn with_platform(mut self, platform: crate::portable::Platform) -> Repo {

        self.platform = platform;

        self

    }

    pub fn platform(&self) -> crate::portable::Platform {

        self.platform

    }

        let mut fs_entries =

            self.walk_working_copy_with(None, &Self::tracked_kinds(base_snapshot))?;

        self.platform_normalize(&mut fs_entries, base_snapshot);

    /// Read the working copy as the platform left it (spec §7.7): without

    /// executable bits a file keeps the bit it has in the base, and without

    /// symbolic links a plain file where the base has a symlink is that

    /// symlink, written out as its target, not a new file.

    fn platform_normalize(&self, entries: &mut BTreeMap<String, FsEntry>, base: &Snapshot) {

        let p = self.platform;

        if p.exec_bits && p.symlinks {

            return;

        }

        for (path, e) in entries.iter_mut() {

            let Some(f) = base.files.get(path) else {

                continue;

            };

            if !p.symlinks && f.kind == NodeKind::Symlink && e.kind == NodeKind::File {

                e.kind = NodeKind::Symlink;

                e.exec = false;

            }

            if !p.exec_bits && f.kind == NodeKind::File && e.kind == NodeKind::File {

                e.exec = f.mode.exec;

            }

        }

    }

        let mut fs_entries =

        self.platform_normalize(&mut fs_entries, &base_snapshot);

/// Spec §7.7 on a file system without executable bits or symlinks: the

/// recorded bit is kept, and a symlink checked out as a plain file holding

/// its target is still that symlink.

#[cfg(unix)]

#[test]

fn windows_file_systems_keep_exec_bits_and_symlinks() {

    use crate::portable::Platform;

    use std::os::unix::fs::PermissionsExt;

    hermetic();

    let dir = tempfile::tempdir().unwrap();

    let root = dir.path();

    let repo = Repo::init(root).unwrap();

    write(root, "run.sh", b"#!/bin/sh\n");

    fs::set_permissions(root.join("run.sh"), fs::Permissions::from_mode(0o755)).unwrap();

    std::os::unix::fs::symlink("run.sh", root.join("link")).unwrap();

    repo.commit("script and link", &[]).unwrap();

    drop(repo);

    // What checking out on Windows leaves: no exec bit, the link as a file.

    fs::set_permissions(root.join("run.sh"), fs::Permissions::from_mode(0o644)).unwrap();

    fs::remove_file(root.join("link")).unwrap();

    write(root, "link", b"run.sh");

    let win = Repo::open(root).unwrap().with_platform(Platform::windows());

    let s = win.snapshot("oxy status").unwrap();

    assert!(

        s.statuses.is_empty(),

        "nothing changed on Windows: {:?}",

        statuses(&s)

    );

    // Editing the file is a content change, not a mode change; retargeting the link keeps it a link.

    write(root, "run.sh", b"#!/bin/sh\necho hi\n");

    write(root, "link", b"other");

    let h = win.commit("edit on Windows", &[]).unwrap();

    let snap = win.load_state(&[h]).unwrap().materialize();

    assert!(snap.files["run.sh"].mode.exec, "the exec bit survives");

    assert_eq!(snap.files["link"].kind, NodeKind::Symlink);

    // The same working copy read as Linux sees the lost bit and the plain file.

    let linux = Repo::open(root).unwrap();

    assert!(!linux.snapshot("oxy status").unwrap().statuses.is_empty());

}

/// Paths that collide on case-insensitive or Windows file systems are

/// named at checkout there, and by doctor everywhere.

#[test]

fn paths_other_platforms_cannot_hold_are_reported() {

    use crate::portable::Platform;

    hermetic();

    let dir = tempfile::tempdir().unwrap();

    let root = dir.path();

    let repo = Repo::init(root).unwrap();

    write(root, "README.md", b"a\n");

    write(root, "readme.md", b"b\n");

    write(root, "src/aux.c", b"int x;\n");

    let h = repo.commit("unportable", &[]).unwrap();

    let r = repo.doctor(false);

    let port = r.checks.iter().find(|c| c.area == "portability").unwrap();

    assert_eq!(port.health, Health::Warn);

    assert!(

        port.message.contains("differ only in case") && port.message.contains("aux.c"),

        "{}",

        port.message

    );

    let mac = Repo::open(root).unwrap().with_platform(Platform::macos());

    let rep = mac.checkout(&[h], true, "oxy checkout").unwrap();

    assert!(

        rep.notes

            .iter()

            .any(|n| n.contains("README.md and readme.md")),

        "{:?}",

        rep.notes

    );

    assert!(

        !rep.notes.iter().any(|n| n.contains("aux.c")),

        "macOS allows aux.c"

    );

}

- On file systems without executable bits, snapshot keeps each file's recorded executable bit instead of reading it as cleared.

- Paths that a case-insensitive file system (macOS and Windows by default) cannot hold side by side (equal but for case, including a directory's case), and names Windows forbids (the reserved device names such as `CON` and `AUX` with any extension, the characters `<>:"\|?*` and control characters, a trailing dot or space), are reported by checkout on such a platform, and by `oxy doctor` (§21.2) on every platform so they can be renamed before anyone meets them.

*Changelog.* Draft 0.8i (2026-09-28): portability rules for exec bits and path names (§7.7); found by verifying a real Git import commit by commit: deletions depend on the inserters of the lines right after them, and replacements on the change that set their old blob (§8.1); replace records are superseded causally, so a reverted binary keeps its blob (§9.3); merges resolve opaque conflicts to the commit's blob, and `oxy git verify` (§23). Draft 0.8h (2026-09-28): `oxy fsck` (§21.1); durability rules and the operation head as commit point (§13.6); the operation head moves by compare-and-swap and concurrent operations are merged (§12.1); `oxy doctor` (§21.2). Draft 0.8g (2026-09-27): delegates of a rule's identities may sign reference attestations (§14.5); local-path pushes bind unbound repositories like HTTP ones. Draft 0.8f (2026-09-27): challenge signatures (§14.3) for hosts. Draft 0.8e (2026-09-27): anonymous changes (zero author) are authenticated by a seal from any key, so imported and pre-identity history can be pushed under a policy (§14.4). Draft 0.8d (2026-09-27): unbound hosted repositories adopt the first pusher's id (§16.1). Draft 0.8c (2026-09-27): bare repositories (`oxy init --bare`, §12.2: no workspace, no working copy; hosting) and the reference server as an embeddable library (§15.1). Draft 0.8b (2026-09-27): the machine interface for editors (§24): `root`, `cat`, `version`, `hunks`, `discard`, and `--json` on the reporting commands.