//! A crate with file-system specific utilities. //! //! ## Examples //! //! ``` //! # fn main() -> Result<(), Box> { //! use std::path::{Path, PathBuf}; //! //! use gix_fs::{ //! stack::{Delegate, ToNormalPathComponents}, //! Stack, //! }; //! //! let components = "src/lib.rs" //! .to_normal_path_components() //! .collect::, _>>()?; //! assert_eq!( //! components //! .into_iter() //! .map(|component| component.to_string_lossy().into_owned()) //! .collect::>(), //! vec!["src", "lib.rs"] //! ); //! //! #[derive(Default)] //! struct Recorder { //! directories: Vec, //! paths: Vec, //! } //! //! impl Delegate for Recorder { //! fn push_directory(&mut self, stack: &Stack) -> std::io::Result<()> { //! self.directories.push(stack.current_relative().to_path_buf()); //! Ok(()) //! } //! //! fn push(&mut self, _is_last_component: bool, stack: &Stack) -> std::io::Result<()> { //! self.paths.push(stack.current_relative().to_path_buf()); //! Ok(()) //! } //! //! fn pop_directory(&mut self) {} //! } //! //! # let dir = tempfile::tempdir()?; //! let capabilities = gix_fs::Capabilities::probe_dir(dir.path()); //! let mut stack = Stack::new(dir.path().to_path_buf()); //! let mut recorder = Recorder::default(); //! stack.make_relative_path_current("src/lib.rs", &mut recorder)?; //! //! assert_eq!(stack.current_relative(), Path::new("src/lib.rs")); //! assert_eq!(recorder.directories[0], Path::new("")); //! assert_eq!(recorder.paths, vec![PathBuf::from("src"), PathBuf::from("src/lib.rs")]); //! assert_eq!(gix_fs::current_dir(capabilities.precompose_unicode)?, std::env::current_dir()?); //! # Ok(()) } //! ``` #![deny(missing_docs)] #![forbid(unsafe_code)] use std::path::PathBuf; /// Common knowledge about the worktree that is needed across most interactions with the work tree #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)] pub struct Capabilities { /// If `true`, the filesystem will consider the precomposed umlaut `ä` similar to its decomposed form `"a\u{308}"` and consider them the same. /// If `false`, the filesystem will only see bytes which means that the above example could live side-by-side. /// /// Even though a filesystem that treats both forms the same will still reproduce the exact same byte sequence during traversal for instance, /// this might also mean that we see paths in their decomposed form (this happens when creating directory `ä` in MacOS Finder for example). /// /// If Git would store such decomposed paths in the repository, which only sees bytes, on linux this might mean the path will look strange /// at best, which is why it prefers to store precomposed unicode on systems where it matters, like MacOS and Windows. /// /// For best compatibility, and with this value being `true`, we will turn decomposed paths and input like command-line arguments into their /// precomposed forms, so no decomposed byte sequences should end up in storage. pub precompose_unicode: bool, /// If true, the filesystem ignores the case of input, which makes `A` the same file as `a`. /// This is also called case-folding. pub ignore_case: bool, /// If true, we assume the executable bit is honored as part of the files mode. If false, we assume the file system /// ignores the executable bit, hence it will be reported as 'off' even though we just tried to set it to be on. pub executable_bit: bool, /// If true, the file system supports symbolic links and we should try to create them. Otherwise symbolic links will be checked /// out as files which contain the link as text. pub symlink: bool, } mod capabilities; mod snapshot; pub use snapshot::{FileSnapshot, SharedFileSnapshot, SharedFileSnapshotMut}; /// pub mod symlink; /// pub mod read_dir; pub use read_dir::function::read_dir; /// pub mod dir; /// Like [`std::env::current_dir()`], but it will `precompose_unicode` if that value is true, if the current directory /// is valid unicode and if there are decomposed unicode codepoints. /// /// Thus, it will turn `"a\u{308}"` into `ä` if `true`. /// Keeping it `false` will not alter the output. /// /// Note that `precompose_unicode` most be set using the `core.precomposeUnicode` git configuration. pub fn current_dir(precompose_unicode: bool) -> std::io::Result { let cwd = std::env::current_dir()?; Ok(if precompose_unicode { gix_utils::str::precompose_path(cwd.into()).into_owned() } else { cwd }) } /// Adjust `permissions` according to Git's shared-repository permission policy. /// /// `permissions` should normally be the permissions of a newly created entry, read back after the operating system has /// applied the process umask. Apply this function before the file is made visible at its final path. Existing permission /// bits not governed by the policy are preserved. /// Read-only files stay read-only, and executable files gain execute bits wherever the policy grants read access. /// Directory permissions must retain the file-type bits returned by metadata: directories gain search permissions /// alongside read permissions, and setgid where the platform needs it to inherit the parent directory's group. /// /// `shared_repository_permissions` uses Git's compact signed encoding and usually comes from parsing the effective /// `core.sharedRepository` configuration value: /// /// - `0` leaves the permissions produced by the umask unchanged. An absent key, `umask`, boolean `false`, and legacy /// value `0` produce this. /// - A positive mode is ORed into the post-umask mode. A bare key, `group`, boolean `true`, and legacy value `1` usually /// produce `0o660`; `all`, `world`, `everybody`, and legacy value `2` usually produce `0o664`. /// - A negative mode replaces the low nine Unix permission bits with its absolute value. Git-compatible parsers use this /// for explicit octal configuration such as `0640`, represented here as `-0o640`, so it can remove bits allowed by the /// umask instead of merely adding bits. /// /// Callers must pass the parsed encoding, not an explicit octal configuration value directly. On non-Unix platforms the /// shared-repository mode has no portable representation in [`std::fs::Permissions`], so this function returns /// `permissions` unchanged. pub fn adjust_shared_repository_permissions( permissions: std::fs::Permissions, shared_repository_permissions: i32, ) -> std::fs::Permissions { #[cfg(unix)] { use std::os::unix::fs::PermissionsExt; if shared_repository_permissions == 0 { return permissions; } let mut permissions = permissions; let mode = permissions.mode(); // Follow Git's calc_shared_perm() in path.c. let mut tweak = shared_repository_permissions.unsigned_abs(); if mode & 0o200 == 0 { tweak &= !0o222; } if mode & 0o100 != 0 { tweak |= (tweak & 0o444) >> 2; } let mut adjusted = if shared_repository_permissions < 0 { (mode & !0o777) | tweak } else { mode | tweak }; // Directory handling follows Git's adjust_shared_perm() in path.c. if mode & 0o170000 == 0o040000 { adjusted |= (adjusted & 0o444) >> 2; // Git's DIR_HAS_BSD_GROUP_SEMANTICS defaults exclude Darwin. if !cfg!(any(target_os = "freebsd", target_os = "openbsd")) && adjusted & 0o060 != 0 { adjusted |= 0o2000; } } permissions.set_mode(adjusted); permissions } #[cfg(not(unix))] { let _ = shared_repository_permissions; permissions } } /// Apply the parsed Git sharing policy to an existing entry at `path`, following symbolic links. /// /// See [`adjust_shared_repository_permissions()`] for the policy encoding and directory handling. /// No metadata is read or written for the default policy (`0`) or on non-Unix platforms. pub fn set_shared_repository_permissions( path: &std::path::Path, shared_repository_permissions: i32, ) -> std::io::Result<()> { #[cfg(unix)] if shared_repository_permissions != 0 { let current = std::fs::metadata(path)?.permissions(); let adjusted = adjust_shared_repository_permissions(current.clone(), shared_repository_permissions); if current != adjusted { std::fs::set_permissions(path, adjusted)?; } } #[cfg(not(unix))] let _ = (path, shared_repository_permissions); Ok(()) } /// A stack of path components with the delegation of side-effects as the currently set path changes, component by component. #[derive(Clone)] pub struct Stack { /// The prefix/root for all paths we handle. root: PathBuf, /// the most recent known cached that we know is valid. current: PathBuf, /// The relative portion of `valid` that was added previously. current_relative: PathBuf, /// The amount of path components of 'current' beyond the roots components. valid_components: usize, /// If set, we assume the `current` element is a directory to affect calls to `(push|pop)_directory()`. current_is_directory: bool, } #[cfg(unix)] /// Returns whether a file has the executable permission set. pub fn is_executable(metadata: &std::fs::Metadata) -> bool { use std::os::unix::fs::MetadataExt; (metadata.mode() & 0o111) != 0 } /// Classifiers for IO-errors. pub mod io_err { use std::io::ErrorKind; /// Return `true` if `err` indicates that the entry doesn't exist on disk. pub fn is_not_found(err: ErrorKind, _raw_err: Option) -> bool { err == ErrorKind::NotFound || err == ErrorKind::NotADirectory } } #[cfg(not(unix))] /// Returns whether a file has the executable permission set. pub fn is_executable(_metadata: &std::fs::Metadata) -> bool { false } /// pub mod stack;