gix_path/lib.rs
1//! This crate contains an assortment of utilities to deal with paths and their conversions.
2//!
3//! Git treats paths as bytes, using UTF-8 for native path conversion on Windows. Paths in Git files use
4//! slashes as separators, with conversions to native separators performed on Windows as needed.
5//!
6//! ## Examples
7//!
8//! ```
9//! use bstr::ByteSlice;
10//!
11//! use std::path::Path;
12//!
13//! let normalized = gix_path::normalize(Path::new("a/./b/..").into(), Path::new("/cwd")).unwrap();
14//! assert_eq!(normalized.as_ref(), Path::new("a"));
15//!
16//! let unix = gix_path::to_unix_separators(b"dir\\subdir\\file".as_bstr());
17//! assert_eq!(unix.as_ref(), b"dir/subdir/file".as_bstr());
18//! ```
19//!
20//! ## Path encodings
21//!
22//! Unix paths contain arbitrary bytes, which these conversions preserve without UTF-8 validation.
23//! Windows paths use potentially ill-formed UTF-16: even modern Windows permits unpaired surrogate
24//! code units. Such paths cannot be represented losslessly as UTF-8, so conversion to Git path bytes
25//! returns an error. Likewise, converting Git path bytes to a native path requires valid UTF-8 on
26//! non-Unix platforms. Valid surrogate pairs, including those used for emoji, convert normally.
27//!
28//! Conversions preserve borrowed and owned inputs and report encoding failures through
29//! [`gix_error::Result`], retaining the concrete encoding error as a source.
30#![deny(missing_docs)]
31#![cfg_attr(not(test), deny(unsafe_code))]
32
33/// A dummy type to represent path specs and help finding all spots that take path specs once it is implemented.
34mod convert;
35pub use convert::*;
36
37mod util;
38pub use util::{is_absolute, windows_drive_prefix};
39
40///
41pub mod realpath;
42pub use realpath::function::{realpath, realpath_opts};
43
44/// Information about the environment in terms of locations of resources.
45pub mod env;
46
47///
48pub mod relative_path;
49pub use relative_path::types::RelativePath;