pub struct File { /* private fields */ }
Expand description
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§
source§impl File
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.
sourcepub fn config(&self) -> &File<'static>
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.
sourcepub fn config_path(&self) -> Option<&Path>
pub fn config_path(&self) -> Option<&Path>
Return the path at which the .gitmodules
file lives, if it is known.
sourcepub fn names(&self) -> impl Iterator<Item = &BStr>
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.
sourcepub 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>
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.
sourcepub fn is_active_platform(
&self,
config: &File<'_>,
defaults: Defaults,
) -> Result<IsActivePlatform, Error>
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.
sourcepub fn name_by_path(&self, relative_path: &BStr) -> Option<&BStr>
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.
source§impl File
impl File
Per-Submodule Access
sourcepub fn path(&self, name: &BStr) -> Result<Cow<'_, BStr>, Error>
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.
sourcepub fn url(&self, name: &BStr) -> Result<Url, Error>
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.
sourcepub fn update(&self, name: &BStr) -> Result<Option<Update>, Error>
pub fn update(&self, name: &BStr) -> Result<Option<Update>, Error>
Retrieve the update
field of the submodule named name
, if present.
sourcepub fn branch(&self, name: &BStr) -> Result<Option<Branch>, Error>
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
.
sourcepub fn fetch_recurse(&self, name: &BStr) -> Result<Option<FetchRecurse>, Error>
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.
source§impl File
impl File
Lifecycle
sourcepub fn from_bytes(
bytes: &[u8],
path: impl Into<Option<PathBuf>>,
config: &File<'_>,
) -> Result<Self, Error>
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.
sourcepub fn into_config(self) -> File<'static>
pub fn into_config(self) -> File<'static>
Turn ourselves into the underlying parsed configuration file.
source§impl File
impl File
Mutation
sourcepub fn append_submodule_overrides(&mut self, config: &File<'_>) -> &mut Self
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§
Auto Trait Implementations§
impl Freeze for File
impl RefUnwindSafe for File
impl !Send for File
impl !Sync for File
impl Unpin for File
impl UnwindSafe for File
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)