Struct File

pub struct File { /* private fields */ }

All relevant information about a git module, typically from .gitmodules files.

Note that overrides from other configuration might be relevant, which is why this type can be used to take these into consideration when presented with other configuration from the superproject.

Implementations

impl File

High-Level Access

Note that all methods perform validation of the requested value and report issues right away. If a bypass is needed, use config() for direct access.

pub fn config(&self) -> &File<'static>

Return the underlying configuration file.

Note that it might have been merged with values from another configuration file and may thus not be accurately reflecting that state of a .gitmodules file anymore.

pub fn config_path(&self) -> Option<&Path>

Return the path at which the .gitmodules file lives, if it is known.

pub fn names(&self) -> impl Iterator<Item = &BStr>

Return the unvalidated names of the submodules for which configuration is present.

Note that these exact names have to be used for querying submodule values.

pub fn names_and_active_state<'a>( &'a self, config: &'a File<'static>, defaults: Defaults, attributes: &'a mut (dyn FnMut(&BStr, Case, bool, &mut Outcome) -> bool + 'a), ) -> Result<impl Iterator<Item = (&'a BStr, Result<bool, Error>)> + 'a, Error>

Similar to Self::is_active_platform(), but automatically applies it to each name to learn if a submodule is active or not.

pub fn is_active_platform( &self, config: &File<'_>, defaults: Defaults, ) -> Result<IsActivePlatform, Error>

Return a platform which allows to check if a submodule name is active or inactive. Use defaults for parsing the pathspecs used to later match on names via submodule.active configuration retrieved from config.

All submodule.active pathspecs are considered to be top-level specs and match the name of submodules, which are active on inclusive match. The full algorithm is described as hierarchy of rules.

pub fn name_by_path(&self, relative_path: &BStr) -> Option<&BStr>

Given the relative_path (as seen from the root of the worktree) of a submodule with possibly platform-specific component separators, find the submodule’s name associated with this path, or None if none was found.

Note that this does a linear search and compares relative_path in a normalized form to the same form of the path associated with the submodule.

impl File

Per-Submodule Access

pub fn path(&self, name: &BStr) -> Result<Cow<'_, BStr>, Error>

Return the path relative to the root directory of the working tree at which the submodule is expected to be checked out. It’s an error if the path doesn’t exist as it’s the only way to associate a path in the index with additional submodule information, like the URL to fetch from.

Deviation

Git currently allows absolute paths to be used when adding submodules, but fails later as it can’t find the submodule by relative path anymore. Let’s play it safe here.

pub fn url(&self, name: &BStr) -> Result<Url, Error>

Retrieve the url field of the submodule named name. It’s an error if it doesn’t exist or is empty.

pub fn update(&self, name: &BStr) -> Result<Option<Update>, Error>

Retrieve the update field of the submodule named name, if present.

pub fn branch(&self, name: &BStr) -> Result<Option<Branch>, Error>

Retrieve the branch field of the submodule named name, or None if unset.

Note that Default is implemented for Branch.

pub fn fetch_recurse(&self, name: &BStr) -> Result<Option<FetchRecurse>, Error>

Retrieve the fetchRecurseSubmodules field of the submodule named name, or None if unset.

Note that if it’s unset, it should be retrieved from fetch.recurseSubmodules in the configuration.

pub fn ignore(&self, name: &BStr) -> Result<Option<Ignore>, Error>

Retrieve the ignore field of the submodule named name, or None if unset.

pub fn shallow(&self, name: &BStr) -> Result<Option<bool>, Error>

Retrieve the shallow field of the submodule named name, or None if unset.

If true, the submodule will be checked out with depth = 1. If unset, false is assumed.

impl File

Lifecycle

pub fn from_bytes( bytes: &[u8], path: impl Into<Option<PathBuf>>, config: &File<'_>, ) -> Result<Self, Error>

Parse bytes as git configuration, typically from .gitmodules, without doing any further validation. path can be provided to keep track of where the file was read from in the underlying config instance. config is used to apply value overrides, which can be empty if overrides should be applied at a later time.

Future access to the module information is lazy and configuration errors are exposed there on a per-value basis.

Security Considerations

The information itself should be used with care as it can direct the caller to fetch from remotes. It is, however, on the caller to assure the input data can be trusted.

pub fn into_config(self) -> File<'static>

Turn ourselves into the underlying parsed configuration file.

impl File

Mutation

pub fn append_submodule_overrides(&mut self, config: &File<'_>) -> &mut Self

This can be used to let config override some values we know about submodules, namely…

• url
• fetchRecurseSubmodules
• ignore
• update
• branch

These values aren’t validated yet, which will happen upon query.

Trait Implementations

impl Clone for File

fn clone(&self) -> File

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for File

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.