Expand description
This crate contains an assortment of utilities to deal with paths and their conversions.
Git treats paths as bytes, using UTF-8 for native path conversion on Windows. Paths in Git files use slashes as separators, with conversions to native separators performed on Windows as needed.
§Examples
use bstr::ByteSlice;
use std::path::Path;
let normalized = gix_path::normalize(Path::new("a/./b/..").into(), Path::new("/cwd")).unwrap();
assert_eq!(normalized.as_ref(), Path::new("a"));
let unix = gix_path::to_unix_separators(b"dir\\subdir\\file".as_bstr());
assert_eq!(unix.as_ref(), b"dir/subdir/file".as_bstr());§Path encodings
Unix paths contain arbitrary bytes, which these conversions preserve without UTF-8 validation. Windows paths use potentially ill-formed UTF-16: even modern Windows permits unpaired surrogate code units. Such paths cannot be represented losslessly as UTF-8, so conversion to Git path bytes returns an error. Likewise, converting Git path bytes to a native path requires valid UTF-8 on non-Unix platforms. Valid surrogate pairs, including those used for emoji, convert normally.
Conversions preserve borrowed and owned inputs and report encoding failures through
gix_error::Result, retaining the concrete encoding error as a source.
Modules§
- env
- Information about the environment in terms of locations of resources.
- realpath
- relative_
path
Structs§
- Relative
Path - A wrapper for
BStr. It is used to enforce the following constraints:
Functions§
- from_
bstr - Similar to
from_byte_slice(), but takes either borrowed or ownedinput. - from_
bstring - Similar to
from_bstr(), but takes and produces owned data. - from_
byte_ slice - Given
inputbytes, produce aPathfrom them ignoring encoding entirely if on Unix. - into_
bstr - Convert the given path either into its raw bytes on Unix or its UTF-8 encoded counterpart on non-Unix platforms.
- is_
absolute - return true if
pathis absolute, which depends on the platform but is always true if it starts with aslash, hence looks like a linux path. - join_
bstr_ unix_ pathsep - Join
pathtobasesuch that they are separated with a/, i.e.base/path. - normalize
- Resolve relative components virtually, eliminating intermediate
..without accessing the filesystem. - normalize_
and_ clean - Like
normalize(), but also removes.components and duplicate or trailing separators. - normalize_
saturating - Like
normalize(), but treats..components beyond the filesystem root as no-ops. Returns an error if normalization exhausts an empty or relativecurrent_dir. - os_
str_ into_ bstr - Like
into_bstr(), but takesOsStras input for a lossless, but fallible, conversion. - os_
string_ into_ bstring - Like
into_bstr(), but takesOsStringas input for a lossless, but fallible, conversion. - realpath
- Check each component of
pathand see if it is a symlink. If so, resolve it. Do not fail for non-existing components, but assume these are as is. - realpath_
opts - The same as
realpath(), but allow to configuremax_symlinksto configure how many symbolic links we are going to follow. This serves to avoid running into cycles or doing unreasonable amounts of work. - relativize_
with_ prefix - Rebuild
relative_pathto be relative toprefix, such as the user’s current working directory. - to_
native_ path_ on_ windows - Convert paths with slashes to backslashes on Windows and do nothing on Unix, returning an error for invalid UTF-8 on non-Unix platforms.
- to_
native_ separators - Assures the given bytes use the native path separator.
- to_
unix_ separators - Replace Windows path separators with slashes, which typically resembles a Unix path, unconditionally.
- to_
unix_ separators_ on_ windows - Replace Windows path separators with slashes, but only do so on Windows.
- to_
windows_ separators - Find slashes and replace them with backslashes, unconditionally.
- try_
os_ str_ into_ bstr - Like
into_bstr(), but takesCow<OsStr>as input for a lossless, but fallible, conversion. - windows_
drive_ prefix - Return the leading Windows drive prefix, including
:, if present, on any platform. Virtual drives created withsubstcan use any Unicode character instead of an ASCII letter.