Struct git_repository::config::Snapshot

pub struct Snapshot<'repo> { /* private fields */ }

A platform to access configuration values as read from disk.

Note that these values won’t update even if the underlying file(s) change.

Implementations

impl<'repo> Snapshot<'repo>

Access configuration values, frozen in time, using a key which is a . separated string of up to three tokens, namely section_name.[subsection_name.]value_name, like core.bare or remote.origin.url.

Note that single-value methods always return the last value found, which is the one set most recently in the hierarchy of configuration files, aka ‘last one wins’.

pub fn boolean<'a>(&self, key: impl Into<&'a BStr>) -> Option<bool>

Return the boolean at key, or None if there is no such value or if the value can’t be interpreted as boolean.

For a non-degenerating version, use try_boolean(…).

Note that this method takes the most recent value at key even if it is from a file with reduced trust.

pub fn try_boolean<'a>(
    &self,
    key: impl Into<&'a BStr>
) -> Option<Result<bool, Error>>

Like boolean(), but it will report an error if the value couldn’t be interpreted as boolean.

pub fn integer<'a>(&self, key: impl Into<&'a BStr>) -> Option<i64>

Return the resolved integer at key, or None if there is no such value or if the value can’t be interpreted as integer or exceeded the value range.

For a non-degenerating version, use try_integer(…).

Note that this method takes the most recent value at key even if it is from a file with reduced trust.

pub fn try_integer<'a>(
    &self,
    key: impl Into<&'a BStr>
) -> Option<Result<i64, Error>>

Like integer(), but it will report an error if the value couldn’t be interpreted as boolean.

pub fn string<'a>(&self, key: impl Into<&'a BStr>) -> Option<Cow<'_, BStr>>

Return the string at key, or None if there is no such value.

Note that this method takes the most recent value at key even if it is from a file with reduced trust.

pub fn trusted_path<'a>(
    &self,
    key: impl Into<&'a BStr>
) -> Option<Result<Cow<'_, Path>, Error>>

Return the trusted and fully interpolated path at key, or None if there is no such value or if no value was found in a trusted file. An error occurs if the path could not be interpolated to its final value.

impl<'repo> Snapshot<'repo>

Utilities and additional access

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

Returns the underlying configuration implementation for a complete API, despite being a little less convenient.

It’s expected that more functionality will move up depending on demand.

impl Snapshot<'_>

pub fn credential_helpers(
    &self,
    url: Url
) -> Result<(Cascade, Action, Options<'static>), Error>

Returns the configuration for all git-credential helpers from trusted configuration that apply to the given url along with an action preconfigured to invoke the cascade with. This includes url which may be altered to contain a user-name as configured.

These can be invoked to obtain credentials. Note that the url is expected to be the one used to connect to a remote, and thus should already have passed the url-rewrite engine.

Deviation

• Invalid urls can’t be used to obtain credential helpers as they are rejected early when creating a valid url here.
• Parsed urls will automatically drop the port if it’s the default, i.e. http://host:80 becomes http://host when parsed. This affects the prompt provided to the user, so that git will use the verbatim url, whereas we use http://host.
• Upper-case scheme and host will be lower-cased automatically when parsing into a url, so prompts differ compared to git.
• A difference in prompt might affect the matching of getting existing stored credentials, and it’s a question of this being a feature or a bug.

Methods from Deref<Target = File<'static>>

pub fn string(
    &self,
    section_name: impl AsRef<str>,
    subsection_name: Option<&BStr>,
    key: impl AsRef<str>
) -> Option<Cow<'_, BStr>>

Like value(), but returning None if the string wasn’t found.

As strings perform no conversions, this will never fail.

pub fn string_by_key<'a>(
    &self,
    key: impl Into<&'a BStr>
) -> Option<Cow<'_, BStr>>

Like string(), but suitable for statically known keys like remote.origin.url.

pub fn string_filter(
    &self,
    section_name: impl AsRef<str>,
    subsection_name: Option<&BStr>,
    key: impl AsRef<str>,
    filter: &mut (dyn FnMut(&Metadata) -> bool + 'static)
) -> Option<Cow<'_, BStr>>

Like string(), but the section containing the returned value must pass filter as well.

pub fn string_filter_by_key<'a>(
    &self,
    key: impl Into<&'a BStr>,
    filter: &mut (dyn FnMut(&Metadata) -> bool + 'static)
) -> Option<Cow<'_, BStr>>

Like string_filter(), but suitable for statically known keys like remote.origin.url.

pub fn path(
    &self,
    section_name: impl AsRef<str>,
    subsection_name: Option<&BStr>,
    key: impl AsRef<str>
) -> Option<Path<'_>>

Like value(), but returning None if the path wasn’t found.

Note that this path is not vetted and should only point to resources which can’t be used to pose a security risk. Prefer using path_filter() instead.

As paths perform no conversions, this will never fail.

pub fn path_by_key<'a>(&self, key: impl Into<&'a BStr>) -> Option<Path<'_>>

Like path(), but suitable for statically known keys like remote.origin.url.

pub fn path_filter(
    &self,
    section_name: impl AsRef<str>,
    subsection_name: Option<&BStr>,
    key: impl AsRef<str>,
    filter: &mut (dyn FnMut(&Metadata) -> bool + 'static)
) -> Option<Path<'_>>

Like path(), but the section containing the returned value must pass filter as well.

This should be the preferred way of accessing paths as those from untrusted locations can be

As paths perform no conversions, this will never fail.

pub fn path_filter_by_key<'a>(
    &self,
    key: impl Into<&'a BStr>,
    filter: &mut (dyn FnMut(&Metadata) -> bool + 'static)
) -> Option<Path<'_>>

Like path_filter(), but suitable for statically known keys like remote.origin.url.

pub fn boolean(
    &self,
    section_name: impl AsRef<str>,
    subsection_name: Option<&BStr>,
    key: impl AsRef<str>
) -> Option<Result<bool, Error>>

Like value(), but returning None if the boolean value wasn’t found.

pub fn boolean_by_key<'a>(
    &self,
    key: impl Into<&'a BStr>
) -> Option<Result<bool, Error>>

Like boolean(), but suitable for statically known keys like remote.origin.url.

pub fn boolean_filter(
    &self,
    section_name: impl AsRef<str>,
    subsection_name: Option<&BStr>,
    key: impl AsRef<str>,
    filter: &mut (dyn FnMut(&Metadata) -> bool + 'static)
) -> Option<Result<bool, Error>>

Like boolean(), but the section containing the returned value must pass filter as well.

pub fn boolean_filter_by_key<'a>(
    &self,
    key: impl Into<&'a BStr>,
    filter: &mut (dyn FnMut(&Metadata) -> bool + 'static)
) -> Option<Result<bool, Error>>

Like boolean_filter(), but suitable for statically known keys like remote.origin.url.

pub fn integer(
    &self,
    section_name: impl AsRef<str>,
    subsection_name: Option<&BStr>,
    key: impl AsRef<str>
) -> Option<Result<i64, Error>>

Like value(), but returning an Option if the integer wasn’t found.

pub fn integer_by_key<'a>(
    &self,
    key: impl Into<&'a BStr>
) -> Option<Result<i64, Error>>

Like integer(), but suitable for statically known keys like remote.origin.url.

pub fn integer_filter(
    &self,
    section_name: impl AsRef<str>,
    subsection_name: Option<&BStr>,
    key: impl AsRef<str>,
    filter: &mut (dyn FnMut(&Metadata) -> bool + 'static)
) -> Option<Result<i64, Error>>

Like integer(), but the section containing the returned value must pass filter as well.

pub fn integer_filter_by_key<'a>(
    &self,
    key: impl Into<&'a BStr>,
    filter: &mut (dyn FnMut(&Metadata) -> bool + 'static)
) -> Option<Result<i64, Error>>

Like integer_filter(), but suitable for statically known keys like remote.origin.url.

pub fn strings(
    &self,
    section_name: impl AsRef<str>,
    subsection_name: Option<&BStr>,
    key: impl AsRef<str>
) -> Option<Vec<Cow<'_, BStr>, Global>>

Similar to values(…) but returning strings if at least one of them was found.

pub fn strings_by_key<'a>(
    &self,
    key: impl Into<&'a BStr>
) -> Option<Vec<Cow<'_, BStr>, Global>>

Like strings(), but suitable for statically known keys like remote.origin.url.

pub fn strings_filter(
    &self,
    section_name: impl AsRef<str>,
    subsection_name: Option<&BStr>,
    key: impl AsRef<str>,
    filter: &mut (dyn FnMut(&Metadata) -> bool + 'static)
) -> Option<Vec<Cow<'_, BStr>, Global>>

Similar to strings(…), but all values are in sections that passed filter.

pub fn strings_filter_by_key<'a>(
    &self,
    key: impl Into<&'a BStr>,
    filter: &mut (dyn FnMut(&Metadata) -> bool + 'static)
) -> Option<Vec<Cow<'_, BStr>, Global>>

Like strings_filter(), but suitable for statically known keys like remote.origin.url.

pub fn integers(
    &self,
    section_name: impl AsRef<str>,
    subsection_name: Option<&BStr>,
    key: impl AsRef<str>
) -> Option<Result<Vec<i64, Global>, Error>>

Similar to values(…) but returning integers if at least one of them was found and if none of them overflows.

pub fn integers_by_key<'a>(
    &self,
    key: impl Into<&'a BStr>
) -> Option<Result<Vec<i64, Global>, Error>>

Like integers(), but suitable for statically known keys like remote.origin.url.

pub fn integers_filter(
    &self,
    section_name: impl AsRef<str>,
    subsection_name: Option<&BStr>,
    key: impl AsRef<str>,
    filter: &mut (dyn FnMut(&Metadata) -> bool + 'static)
) -> Option<Result<Vec<i64, Global>, Error>>

Similar to integers(…) but all integers are in sections that passed filter and that are not overflowing.

pub fn integers_filter_by_key<'a>(
    &self,
    key: impl Into<&'a BStr>,
    filter: &mut (dyn FnMut(&Metadata) -> bool + 'static)
) -> Option<Result<Vec<i64, Global>, Error>>

Like integers_filter(), but suitable for statically known keys like remote.origin.url.

pub fn raw_value(
    &self,
    section_name: impl AsRef<str>,
    subsection_name: Option<&BStr>,
    key: impl AsRef<str>
) -> Result<Cow<'_, BStr>, Error>

Returns an uninterpreted value given a section, an optional subsection and key.

Consider Self::raw_values() if you want to get all values of a multivar instead.

pub fn raw_value_filter(
    &self,
    section_name: impl AsRef<str>,
    subsection_name: Option<&BStr>,
    key: impl AsRef<str>,
    filter: &mut (dyn FnMut(&Metadata) -> bool + 'static)
) -> Result<Cow<'_, BStr>, Error>

Returns an uninterpreted value given a section, an optional subsection and key, if it passes the filter.

Consider Self::raw_values() if you want to get all values of a multivar instead.

pub fn raw_values(
    &self,
    section_name: impl AsRef<str>,
    subsection_name: Option<&BStr>,
    key: impl AsRef<str>
) -> Result<Vec<Cow<'_, BStr>, Global>, Error>

Returns all uninterpreted values given a section, an optional subsection ain order of occurrence.

The ordering means that the last of the returned values is the one that would be the value used in the single-value case.nd key.

Examples

If you have the following config:

[core]
    a = b
[core]
    a = c
    a = d

Attempting to get all values of a yields the following:

assert_eq!(
    git_config.raw_values("core", None, "a").unwrap(),
    vec![
        Cow::<BStr>::Borrowed("b".into()),
        Cow::<BStr>::Borrowed("c".into()),
        Cow::<BStr>::Borrowed("d".into()),
    ],
);

Consider Self::raw_value if you want to get the resolved single value for a given key, if your key does not support multi-valued values.

pub fn raw_values_filter(
    &self,
    section_name: impl AsRef<str>,
    subsection_name: Option<&BStr>,
    key: impl AsRef<str>,
    filter: &mut (dyn FnMut(&Metadata) -> bool + 'static)
) -> Result<Vec<Cow<'_, BStr>, Global>, Error>

Returns all uninterpreted values given a section, an optional subsection and key, if the value passes filter, in order of occurrence.

The ordering means that the last of the returned values is the one that would be the value used in the single-value case.

pub fn value<'a, T>(
    &'a self,
    section_name: &str,
    subsection_name: Option<&BStr>,
    key: &str
) -> Result<T, Error<<T as TryFrom<Cow<'a, BStr>>>::Error>>where
    T: TryFrom<Cow<'a, BStr>>,

Returns an interpreted value given a section, an optional subsection and key.

It’s recommended to use one of the value types provide dby this crate as they implement the conversion, but this function is flexible and will accept any type that implements TryFrom<&BStr>.

Consider Self::values if you want to get all values of a multivar instead.

If a string is desired, use the string() method instead.

Examples

let config = r#"
    [core]
        a = 10k
        c = false
"#;
let git_config = git_config::File::try_from(config)?;
// You can either use the turbofish to determine the type...
let a_value = git_config.value::<Integer>("core", None, "a")?;
// ... or explicitly declare the type to avoid the turbofish
let c_value: Boolean = git_config.value("core", None, "c")?;

pub fn try_value<'a, T>(
    &'a self,
    section_name: &str,
    subsection_name: Option<&BStr>,
    key: &str
) -> Option<Result<T, <T as TryFrom<Cow<'a, BStr>>>::Error>>where
    T: TryFrom<Cow<'a, BStr>>,

Like value(), but returning an None if the value wasn’t found at section[.subsection].key

pub fn values<'a, T>(
    &'a self,
    section_name: &str,
    subsection_name: Option<&BStr>,
    key: &str
) -> Result<Vec<T, Global>, Error<<T as TryFrom<Cow<'a, BStr>>>::Error>>where
    T: TryFrom<Cow<'a, BStr>>,

Returns all interpreted values given a section, an optional subsection and key.

It’s recommended to use one of the value types provide dby this crate as they implement the conversion, but this function is flexible and will accept any type that implements TryFrom<&BStr>.

Consider Self::value if you want to get a single value (following last-one-wins resolution) instead.

To access plain strings, use the strings() method instead.

Examples

let config = r#"
    [core]
        a = true
        c
    [core]
        a
        a = false
"#;
let git_config = git_config::File::try_from(config).unwrap();
// You can either use the turbofish to determine the type...
let a_value = git_config.values::<Boolean>("core", None, "a")?;
assert_eq!(
    a_value,
    vec![
        Boolean(true),
        Boolean(false),
        Boolean(false),
    ]
);
// ... or explicitly declare the type to avoid the turbofish
let c_value: Vec<Boolean> = git_config.values("core", None, "c").unwrap();
assert_eq!(c_value, vec![Boolean(false)]);

pub fn section(
    &self,
    name: impl AsRef<str>,
    subsection_name: Option<&BStr>
) -> Result<&Section<'event>, Error>

Returns the last found immutable section with a given name and optional subsection_name.

pub fn section_by_key<'a>(
    &self,
    key: impl Into<&'a BStr>
) -> Result<&Section<'event>, Error>

Returns the last found immutable section with a given key, identifying the name and subsection name like core or remote.origin.

pub fn section_filter<'a>(
    &'a self,
    name: impl AsRef<str>,
    subsection_name: Option<&BStr>,
    filter: &mut (dyn FnMut(&Metadata) -> bool + 'static)
) -> Result<Option<&'a Section<'event>>, Error>

Returns the last found immutable section with a given name and optional subsection_name, that matches filter.

If there are sections matching section_name and subsection_name but the filter rejects all of them, Ok(None) is returned.

pub fn section_filter_by_key<'b, 'a>(
    &'a self,
    key: impl Into<&'b BStr>,
    filter: &mut (dyn FnMut(&Metadata) -> bool + 'static)
) -> Result<Option<&'a Section<'event>>, Error>

Like section_filter(), but identifies the section with key like core or remote.origin.

pub fn sections_by_name<'a>(
    &'a self,
    name: &'a str
) -> Option<impl Iterator<Item = &'a Section<'event>> + 'a>

Gets all sections that match the provided name, ignoring any subsections.

Examples

Provided the following config:

[core]
    a = b
[core ""]
    c = d
[core "apple"]
    e = f

Calling this method will yield all sections:

let config = r#"
    [core]
        a = b
    [core ""]
        c = d
    [core "apple"]
        e = f
"#;
let git_config = git_config::File::try_from(config)?;
assert_eq!(git_config.sections_by_name("core").map_or(0, |s|s.count()), 3);

pub fn sections_and_ids_by_name<'a>(
    &'a self,
    name: &'a str
) -> Option<impl Iterator<Item = (&'a Section<'event>, SectionId)> + 'a>

Similar to sections_by_name(), but returns an identifier for this section as well to allow referring to it unambiguously even in the light of deletions.

pub fn sections_by_name_and_filter<'a>(
    &'a self,
    name: &'a str,
    filter: &'a mut (dyn FnMut(&Metadata) -> bool + 'static)
) -> Option<impl Iterator<Item = &'a Section<'event>> + 'a>

Gets all sections that match the provided name, ignoring any subsections, and pass the filter.

pub fn num_values(&self) -> usize

Returns the number of values in the config, no matter in which section.

For example, a config with multiple empty sections will return 0. This ignores any comments.

pub fn is_void(&self) -> bool

Returns if there are no entries in the config. This will return true if there are only empty sections, with whitespace and comments not being considered void.

pub fn meta(&self) -> &Metadata

Return the file’s metadata to guide filtering of all values upon retrieval.

This is the metadata the file was instantiated with for use in all newly created sections.

pub fn meta_owned(&self) -> Arc<Metadata>

Similar to meta(), but with shared ownership.

pub fn sections(&self) -> impl Iterator<Item = &Section<'event>>

Return an iterator over all sections, in order of occurrence in the file itself.

pub fn sections_and_ids(
    &self
) -> impl Iterator<Item = (&Section<'event>, SectionId)>

Return an iterator over all sections and their ids, in order of occurrence in the file itself.

pub fn sections_and_postmatter(
    &self
) -> impl Iterator<Item = (&Section<'event>, Vec<&Event<'event>, Global>)>

Return an iterator over all sections along with non-section events that are placed right after them, in order of occurrence in the file itself.

This allows to reproduce the look of sections perfectly when serializing them with write_to().

pub fn frontmatter(&self) -> Option<impl Iterator<Item = &Event<'event>>>

Return all events which are in front of the first of our sections, or None if there are none.

pub fn detect_newline_style(&self) -> &BStr

Return the newline characters that have been detected in this config file or the default ones for the current platform.

Note that the first found newline is the one we use in the assumption of consistency.

pub fn to_bstring(&self) -> BString

Serialize this type into a BString for convenience.

Note that to_string() can also be used, but might not be lossless.

pub fn write_to(&self, out: impl Write) -> Result<(), Error>

Stream ourselves to the given out, in order to reproduce this file mostly losslessly as it was parsed.

Trait Implementations

impl Debug for Snapshot<'_>

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

Formats the value using the given formatter.

impl Deref for Snapshot<'_>

type Target = File<'static>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.