Xgit v0.7.0 Xgit.FilePath View Source
Describes a file path as stored in a git repo.
Paths are always stored as a list of bytes. The git specification does not explicitly specify an encoding, but most commonly the path is interpreted as UTF-8.
We use byte lists here to avoid confusion and possible misintepretation
in Elixir's String
type for non-UTF-8 paths.
Paths are alternately referred to in git as "file name," "path,"
"path name," and "object name." We're using the name FilePath
to avoid collision with Elixir's built-in Path
module and to make
it clear that we're talking about the path to where a file is stored
on disk.
Link to this section Summary
Types
Error codes which can be returned by check_path/2
.
Error codes which can be returned by check_path_segment/2
.
Representation of a file's path within a git repo.
Functions
Check the provided path to see if it is a valid path within a git repository.
Check the provided path segment to see if it is a valid path within a git tree
object.
Compare two paths according to git path sort ordering rules.
Compare two paths, checking for identical name.
Ensure that a trailing /
is present.
Return true
if the filename could be read as a .gitmodules
file when
checked out to the working directory.
Returns true
if path
starts with prefix
.
Remove trailing /
if present.
Return true
if the value is a valid file path.
Link to this section Types
check_path_reason()
View Sourcecheck_path_reason() :: :invalid_name | :empty_path | :absolute_path | :duplicate_slash | :trailing_slash
Error codes which can be returned by check_path/2
.
check_path_segment_reason()
View Sourcecheck_path_segment_reason() :: :invalid_name | :empty_name | :reserved_name | :invalid_utf8_sequence | :invalid_name_on_windows | :windows_device_name
Error codes which can be returned by check_path_segment/2
.
Representation of a file's path within a git repo.
Typically, though not necessarily, interpreted as UTF-8.
Link to this section Functions
check_path(path, opts \\ [])
View Sourcecheck_path(path :: t(), windows?: boolean(), macosx?: boolean()) :: :ok | {:error, check_path_reason()} | {:error, check_path_segment_reason()}
Check the provided path to see if it is a valid path within a git repository.
The rules enforced here are slightly different from what is allowed in a tree
object in that we allow /
characters to build hierarchical paths.
Parameters
path
is a UTF-8 byte list containing the path to be tested.
Options
windows?
:true
to additionally verify that the path is permissible on Windows file systemsmacosx?
:true
to additionally verify that the path is permissible on Mac OS X file systems
Return Values
:ok
if the name is permissible given the constraints chosen above{:error, :invalid_name}
if the name is not permissible{:error, :empty_path}
if the name is empty{:error, :absolute_path}
if the name starts with a/
{:error, :duplicate_slash}
if the name contains two/
characters in a row{:error, :trailing_slash}
if the name contains a trailing/
See also: error return values from check_path_segment/2
.
check_path_segment(path, opts \\ [])
View Sourcecheck_path_segment(path :: t(), windows?: boolean(), macosx?: boolean()) :: :ok | {:error, check_path_segment_reason()}
Check the provided path segment to see if it is a valid path within a git tree
object.
Parameters
path
is a UTF-8 byte list containing the path segment to be tested.
Options
windows?
:true
to additionally verify that the path is permissible on Windows file systemsmacosx?
:true
to additionally verify that the path is permissible on Mac OS X file systems
Return Values
:ok
if the name is permissible given the constraints chosen above{:error, :invalid_name}
if the name is not permissible{:error, :empty_name}
if the name is empty{:error, :reserved_name}
if the name is reserved for git's use (i.e..git
){:error, :invalid_utf8_sequence}
if the name contains certain incomplete UTF-8 byte sequences (only whenmacosx?: true
is selected){:error, :invalid_name_on_windows}
if the name contains characters that are not allowed on Windows file systems (only whenwindows?: true
is selected){:error, :windows_device_name}
if the name matches a Windows device name (aux
, etc.) (only whenwindows?: true
is selected)
compare(path1, mode1, path2, mode2)
View Sourcecompare( path1 :: t(), mode1 :: Xgit.FileMode.t(), path2 :: t(), mode2 :: Xgit.FileMode.t() ) :: Xgit.Util.Comparison.result()
Compare two paths according to git path sort ordering rules.
Return Value
:lt
ifpath1
sorts beforepath2
.:eq
if they are the same.:gt
ifpath1
sorts afterpath2
.
compare_same_name(path1, path2, mode2)
View Sourcecompare_same_name(path1 :: t(), path2 :: t(), mode2 :: Xgit.FileMode.t()) :: Xgit.Util.Comparison.result()
Compare two paths, checking for identical name.
Unlike compare/4
, this method returns :eq
when the paths have
the same characters in their names, even if the mode differs. It is
intended for use in validation routines detecting duplicate entries.
Parameters
mode2
is the mode of the second file. Trees are sorted as though
List.last(path2) == ?/
, even if no such character exists.
Return Value
Returns :eq
if the names are identical and a conflict exists
between path1
and path2
, as they share the same name.
Returns :lt
if all possible occurrences of path1
sort
before path2
and no conflict can happen. In a properly sorted
tree there are no other occurrences of path1
and therefore there
are no duplicate names.
Returns :gt
when it is possible for a duplicate occurrence of
path1
to appear later, after path2
. Callers should
continue to examine candidates for path2
until the method returns
one of the other return values.
Ensure that a trailing /
is present.
Exception: If the path is empty, it will be returned as-is.
Return true
if the filename could be read as a .gitmodules
file when
checked out to the working directory.
This would seem like a simple comparison, but some filesystems have peculiar rules for normalizing filenames:
NTFS has backward-compatibility support for 8.3 synonyms of long file names. (See https://web.archive.org/web/20160318181041/https://usn.pw/blog/gen/2015/06/09/filenames/ for details.) NTFS is also case-insensitive.
MacOS's HFS+ folds away ignorable Unicode characters in addition to case folding.
Parameters
path
is a UTF-8 byte list containing the path to be tested.
Options
By default, this function will only check for the plain .gitmodules
name.
windows?
:true
to additionally check for any path that might be treated as a.gitmodules
file on Windows file systemsmacosx?
:true
to additionally check for any path that might be treated as a.gitmodules
file on Mac OS X file systems
Returns true
if path
starts with prefix
.
Unlike String.starts_with?/2
, only accepts a single prefix path.
Remove trailing /
if present.
Return true
if the value is a valid file path.
This performs the same checks as check_path/2
, but folds away all of the potential
error values to false
.
Parameters
path
is a UTF-8 byte list containing the path to be tested.
Options
windows?
:true
to additionally verify that the path is permissible on Windows file systemsmacosx?
:true
to additionally verify that the path is permissible on Mac OS X file systems