Xgit v0.7.1 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

check_path_reason()

Error codes which can be returned by check_path/2.

check_path_segment_reason()

Error codes which can be returned by check_path_segment/2.

t()

Representation of a file's path within a git repo.

Functions

check_path(path, opts \\ [])

Check the provided path to see if it is a valid path within a git repository.

check_path_segment(path, opts \\ [])

Check the provided path segment to see if it is a valid path within a git tree object.

compare(path1, mode1, path2, mode2)

Compare two paths according to git path sort ordering rules.

compare_same_name(path1, path2, mode2)

Compare two paths, checking for identical name.

ensure_trailing_separator(path)

Ensure that a trailing / is present.

gitmodules?(path, opts \\ [])

Return true if the filename could be read as a .gitmodules file when checked out to the working directory.

starts_with?(path, prefix)

Returns true if path starts with prefix.

strip_trailing_separator(path)

Remove trailing / if present.

valid?(path, opts \\ [])

Return true if the value is a valid file path.

Link to this section Types

check_path_reason()

check_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()

check_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.

t()

t() :: [byte()]

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 \\ [])

check_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 systems
macosx?: 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 \\ [])

check_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 systems
macosx?: 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 when macosx?: true is selected)
{:error, :invalid_name_on_windows} if the name contains characters that are not allowed on Windows file systems (only when windows?: true is selected)
{:error, :windows_device_name} if the name matches a Windows device name (aux, etc.) (only when windows?: true is selected)

compare(path1, mode1, path2, mode2)

compare(
  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 if path1 sorts before path2.
:eq if they are the same.
:gt if path1 sorts after path2.

compare_same_name(path1, path2, mode2)

compare_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_trailing_separator(path)

ensure_trailing_separator(path :: t()) :: t()

Ensure that a trailing / is present.

Exception: If the path is empty, it will be returned as-is.

gitmodules?(path, opts \\ [])

gitmodules?(path :: t(), windows?: boolean(), macosx?: boolean()) ::
  boolean()

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 systems
macosx?: true to additionally check for any path that might be treated as a .gitmodules file on Mac OS X file systems

starts_with?(path, prefix)

starts_with?(path :: t(), prefix :: t()) :: boolean()

Returns true if path starts with prefix.

Unlike String.starts_with?/2, only accepts a single prefix path.

strip_trailing_separator(path)

strip_trailing_separator(path :: t()) :: t()

Remove trailing / if present.

valid?(path, opts \\ [])

valid?(path :: any(), windows?: boolean(), macosx?: boolean()) :: boolean()

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 systems
macosx?: true to additionally verify that the path is permissible on Mac OS X file systems