Struct File

pub struct File<'event> { /* private fields */ }

High level git-config reader and writer.

This is the full-featured implementation that can deserialize, serialize, and edit git-config files without loss of whitespace or comments.

‘multivar’ behavior

git is flexible enough to allow users to set a key multiple times in any number of identically named sections. When this is the case, the key is known as a “multivar”. In this case, raw_value() follows the “last one wins”.

Concretely, the following config has a multivar, a, with the values of b, c, and d, while e is a single variable with the value f g h.

[core]
    a = b
    a = c
[core]
    a = d
    e = f g h

Calling methods that fetch or set only one value (such as raw_value()) key a with the above config will fetch d or replace d, since the last valid config key/value pair is a = d:

Filtering

All methods exist in a *_filter(…, filter) version to allow skipping sections by their metadata. That way it’s possible to select values based on their gix_sec::Trust for example, or by their location.

Note that the filter may be executed even on sections that don’t contain the key in question, even though the section will have matched the name and subsection_name respectively.

assert_eq!(git_config.raw_value("core.a").unwrap().as_ref(), "d");

Consider the multi variants of the methods instead, if you want to work with all values.

Equality

In order to make it useful, equality will ignore all non-value bearing information, hence compare only sections and their names, as well as all of their values. The ordering matters, of course.

Implementations

impl File<'static>

Easy-instantiation of typical non-repository git configuration files with all configuration defaulting to typical values.

Limitations

Note that includeIf conditions in global files will cause failure as the required information to resolve them isn’t present without a repository.

Also note that relevant information to interpolate paths will be obtained from the environment or other source on unix.

pub fn from_globals() -> Result<File<'static>, Error>

Open all global configuration files which involves the following sources:

• git-installation
• system
• globals

which excludes repository local configuration, as well as override-configuration from environment variables.

Note that the file might be empty in case no configuration file was found.

pub fn from_environment_overrides() -> Result<File<'static>, Error>

Generates a config from GIT_CONFIG_* environment variables and return a possibly empty File. A typical use of this is to append this configuration to another one with lower precedence to obtain overrides.

See git-config’s documentation for more information on the environment variables in question.

impl File<'static>

An easy way to provide complete configuration for a repository.

pub fn from_git_dir(dir: PathBuf) -> Result<File<'static>, Error>

This configuration type includes the following sources, in order of precedence:

• globals
• repository-local by loading dir/config
• worktree by loading dir/config.worktree
• environment

Note that dir is the .git dir to load the configuration from, not the configuration file.

Includes will be resolved within limits as some information like the git installation directory is missing to interpolate paths with as well as git repository information like the branch name.

impl File<'static>

Instantiation from environment variables

pub fn from_env(options: Options<'_>) -> Result<Option<File<'static>>, Error>

Generates a config from GIT_CONFIG_* environment variables or returns Ok(None) if no configuration was found. See git-config’s documentation for more information on the environment variables in question.

With options configured, it’s possible to resolve include.path or includeIf.<condition>.path directives as well.

impl File<'static>

Instantiation from one or more paths

pub fn from_path_no_includes( path: PathBuf, source: Source, ) -> Result<Self, Error>

Load the single file at path with source without following include directives.

Note that the path will be checked for ownership to derive trust.

pub fn from_paths_metadata( path_meta: impl IntoIterator<Item = impl Into<Metadata>>, options: Options<'_>, ) -> Result<Option<Self>, Error>

Constructs a git-config file from the provided metadata, which must include a path to read from or be ignored. Returns Ok(None) if there was not a single input path provided, which is a possibility due to Metadata::path being an Option. If an input path doesn’t exist, the entire operation will abort. See from_paths_metadata_buf() for a more powerful version of this method.

pub fn from_paths_metadata_buf( path_meta: &mut dyn Iterator<Item = Metadata>, buf: &mut Vec<u8>, err_on_non_existing_paths: bool, options: Options<'_>, ) -> Result<Option<Self>, Error>

Like from_paths_metadata(), but will use buf to temporarily store the config file contents for parsing instead of allocating an own buffer.

If err_on_nonexisting_paths is false, instead of aborting with error, we will continue to the next path instead.

impl<'a> File<'a>

pub fn new(meta: impl Into<OwnShared<Metadata>>) -> Self

Return an empty File with the given meta-data to be attached to all new sections.

pub fn from_bytes_no_includes( input: &'a [u8], meta: impl Into<OwnShared<Metadata>>, options: Options<'_>, ) -> Result<Self, Error>

Instantiate a new File from given input, associating each section and their values with meta-data, while respecting options.

pub fn from_parse_events_no_includes( _: Events<'a>, meta: impl Into<OwnShared<Metadata>>, ) -> Self

Instantiate a new File from given events, associating each section and their values with meta-data.

impl File<'static>

pub fn from_bytes_owned( input_and_buf: &mut Vec<u8>, meta: impl Into<OwnShared<Metadata>>, options: Options<'_>, ) -> Result<Self, Error>

Instantiate a new fully-owned File from given input (later reused as buffer when resolving includes), associating each section and their values with meta-data, while respecting options, and following includes as configured there.

impl File<'_>

Comfortable API for accessing values

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

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

pub fn string_by( &self, section_name: impl AsRef<str>, subsection_name: Option<&BStr>, value_name: 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_filter( &self, key: impl AsKey, filter: impl FnMut(&Metadata) -> bool, ) -> Option<Cow<'_, BStr>>

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

pub fn string_filter_by( &self, section_name: impl AsRef<str>, subsection_name: Option<&BStr>, value_name: impl AsRef<str>, filter: impl FnMut(&Metadata) -> bool, ) -> Option<Cow<'_, BStr>>

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

pub fn path(&self, key: impl AsKey) -> Option<Path<'_>>

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

pub fn path_by( &self, section_name: impl AsRef<str>, subsection_name: Option<&BStr>, value_name: 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_filter( &self, key: impl AsKey, filter: impl FnMut(&Metadata) -> bool, ) -> Option<Path<'_>>

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

pub fn path_filter_by( &self, section_name: impl AsRef<str>, subsection_name: Option<&BStr>, value_name: impl AsRef<str>, filter: impl FnMut(&Metadata) -> bool, ) -> 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 boolean(&self, key: impl AsKey) -> Option<Result<bool, Error>>

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

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

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

pub fn boolean_filter( &self, key: impl AsKey, filter: impl FnMut(&Metadata) -> bool, ) -> Option<Result<bool, Error>>

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

pub fn boolean_filter_by( &self, section_name: impl AsRef<str>, subsection_name: Option<&BStr>, value_name: impl AsRef<str>, filter: impl FnMut(&Metadata) -> bool, ) -> Option<Result<bool, Error>>

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

pub fn integer(&self, key: impl AsKey) -> Option<Result<i64, Error>>

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

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

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

pub fn integer_filter( &self, key: impl AsKey, filter: impl FnMut(&Metadata) -> bool, ) -> Option<Result<i64, Error>>

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

pub fn integer_filter_by( &self, section_name: impl AsRef<str>, subsection_name: Option<&BStr>, value_name: impl AsRef<str>, filter: impl FnMut(&Metadata) -> bool, ) -> Option<Result<i64, Error>>

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

pub fn strings(&self, key: impl AsKey) -> Option<Vec<Cow<'_, BStr>>>

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

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

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

pub fn strings_filter( &self, key: impl AsKey, filter: impl FnMut(&Metadata) -> bool, ) -> Option<Vec<Cow<'_, BStr>>>

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

pub fn strings_filter_by( &self, section_name: impl AsRef<str>, subsection_name: Option<&BStr>, value_name: impl AsRef<str>, filter: impl FnMut(&Metadata) -> bool, ) -> Option<Vec<Cow<'_, BStr>>>

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

pub fn integers(&self, key: impl AsKey) -> Option<Result<Vec<i64>, Error>>

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

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

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

pub fn integers_filter( &self, key: impl AsKey, filter: impl FnMut(&Metadata) -> bool, ) -> Option<Result<Vec<i64>, Error>>

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

pub fn integers_filter_by( &self, section_name: impl AsRef<str>, subsection_name: Option<&BStr>, value_name: impl AsRef<str>, filter: impl FnMut(&Metadata) -> bool, ) -> Option<Result<Vec<i64>, Error>>

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

impl<'event> File<'event>

Mutating low-level access methods.

pub fn section_mut<'a>( &'a mut self, name: impl AsRef<str>, subsection_name: Option<&BStr>, ) -> Result<SectionMut<'a, 'event>, Error>

Returns the last mutable section with a given name and optional subsection_name, if it exists.

pub fn section_mut_by_key<'a, 'b>( &'a mut self, key: impl Into<&'b BStr>, ) -> Result<SectionMut<'a, 'event>, Error>

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

pub fn section_mut_by_id<'a>( &'a mut self, id: SectionId, ) -> Option<SectionMut<'a, 'event>>

Return the mutable section identified by id, or None if it didn’t exist.

Note that id is stable across deletions and insertions.

pub fn section_mut_or_create_new<'a>( &'a mut self, name: impl AsRef<str>, subsection_name: Option<&BStr>, ) -> Result<SectionMut<'a, 'event>, Error>

Returns the last mutable section with a given name and optional subsection_name, if it exists, or create a new section.

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

Returns an mutable section with a given name and optional subsection_name, if it exists and passes filter, or create a new section.

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

Returns the last found mutable section with a given name and optional subsection_name, that matches filter, if it exists.

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

pub fn section_mut_filter_by_key<'a, 'b>( &'a mut self, key: impl Into<&'b BStr>, filter: impl FnMut(&Metadata) -> bool, ) -> Result<Option<SectionMut<'a, 'event>>, Error>

Like section_mut_filter(), but identifies the with a given key, like core or remote.origin.

pub fn new_section( &mut self, name: impl Into<Cow<'event, str>>, subsection: impl Into<Option<Cow<'event, BStr>>>, ) -> Result<SectionMut<'_, 'event>, Error>

Adds a new section. If a subsection name was provided, then the generated header will use the modern subsection syntax. Returns a reference to the new section for immediate editing.

Examples

Creating a new empty section:

let mut git_config = gix_config::File::default();
let section = git_config.new_section("hello", Some(Cow::Borrowed("world".into())))?;
let nl = section.newline().to_owned();
assert_eq!(git_config.to_string(), format!("[hello \"world\"]{nl}"));

Creating a new empty section and adding values to it:

let mut git_config = gix_config::File::default();
let mut section = git_config.new_section("hello", Some(Cow::Borrowed("world".into())))?;
section.push(section::ValueName::try_from("a")?, Some("b".into()));
let nl = section.newline().to_owned();
assert_eq!(git_config.to_string(), format!("[hello \"world\"]{nl}\ta = b{nl}"));
let _section = git_config.new_section("core", None);
assert_eq!(git_config.to_string(), format!("[hello \"world\"]{nl}\ta = b{nl}[core]{nl}"));

pub fn remove_section<'a>( &mut self, name: impl AsRef<str>, subsection_name: impl Into<Option<&'a BStr>>, ) -> Option<Section<'event>>

Removes the section with name and subsection_name , returning it if there was a matching section. If multiple sections have the same name, then the last one is returned. Note that later sections with the same name have precedent over earlier ones.

Examples

Creating and removing a section:

let mut git_config = gix_config::File::try_from(
r#"[hello "world"]
    some-value = 4
"#)?;

let section = git_config.remove_section("hello", Some("world".into()));
assert_eq!(git_config.to_string(), "");

Precedence example for removing sections with the same name:

let mut git_config = gix_config::File::try_from(
r#"[hello "world"]
    some-value = 4
[hello "world"]
    some-value = 5
"#)?;

let section = git_config.remove_section("hello", Some("world".into()));
assert_eq!(git_config.to_string(), "[hello \"world\"]\n    some-value = 4\n");

pub fn remove_section_by_id(&mut self, id: SectionId) -> Option<Section<'event>>

Remove the section identified by id if it exists and return it, or return None if no such section was present.

Note that section ids are unambiguous even in the face of removals and additions of sections.

pub fn remove_section_filter<'a>( &mut self, name: impl AsRef<str>, subsection_name: impl Into<Option<&'a BStr>>, filter: impl FnMut(&Metadata) -> bool, ) -> Option<Section<'event>>

Removes the section with name and subsection_name that passed filter, returning the removed section if at least one section matched the filter. If multiple sections have the same name, then the last one is returned. Note that later sections with the same name have precedent over earlier ones.

pub fn push_section( &mut self, section: Section<'event>, ) -> SectionMut<'_, 'event>

Adds the provided section to the config, returning a mutable reference to it for immediate editing. Note that its meta-data will remain as is.

pub fn rename_section<'a>( &mut self, name: impl AsRef<str>, subsection_name: impl Into<Option<&'a BStr>>, new_name: impl Into<Cow<'event, str>>, new_subsection_name: impl Into<Option<Cow<'event, BStr>>>, ) -> Result<(), Error>

Renames the section with name and subsection_name, modifying the last matching section to use new_name and new_subsection_name.

pub fn rename_section_filter<'a>( &mut self, name: impl AsRef<str>, subsection_name: impl Into<Option<&'a BStr>>, new_name: impl Into<Cow<'event, str>>, new_subsection_name: impl Into<Option<Cow<'event, BStr>>>, filter: impl FnMut(&Metadata) -> bool, ) -> Result<(), Error>

Renames the section with name and subsection_name, modifying the last matching section that also passes filter to use new_name and new_subsection_name.

Note that the otherwise unused lookup::existing::Error::KeyMissing variant is used to indicate that the filter rejected all candidates, leading to no section being renamed after all.

pub fn append(&mut self, other: Self) -> &mut Self

Append another File to the end of ourselves, without losing any information.

impl<'event> File<'event>

Raw value API

These functions are the raw value API, returning normalized byte strings.

pub fn raw_value(&self, key: impl AsKey) -> Result<Cow<'_, BStr>, Error>

Returns an uninterpreted value given a key.

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

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

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

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

pub fn raw_value_filter( &self, key: impl AsKey, filter: impl FnMut(&Metadata) -> bool, ) -> Result<Cow<'_, BStr>, Error>

Returns an uninterpreted value given a key, if it passes the filter.

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

pub fn raw_value_filter_by( &self, section_name: impl AsRef<str>, subsection_name: Option<&BStr>, value_name: impl AsRef<str>, filter: impl FnMut(&Metadata) -> bool, ) -> Result<Cow<'_, BStr>, Error>

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

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

pub fn raw_value_mut<'lookup>( &mut self, key: &'lookup impl AsKey, ) -> Result<ValueMut<'_, 'lookup, 'event>, Error>

Returns a mutable reference to an uninterpreted value given a section, an optional subsection and value name.

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

pub fn raw_value_mut_by<'lookup>( &mut self, section_name: impl AsRef<str>, subsection_name: Option<&'lookup BStr>, value_name: &'lookup str, ) -> Result<ValueMut<'_, 'lookup, 'event>, Error>

Returns a mutable reference to an uninterpreted value given a section, an optional subsection and value name.

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

pub fn raw_value_mut_filter<'lookup>( &mut self, section_name: impl AsRef<str>, subsection_name: Option<&'lookup BStr>, value_name: &'lookup str, filter: impl FnMut(&Metadata) -> bool, ) -> Result<ValueMut<'_, 'lookup, 'event>, Error>

Returns a mutable reference to an uninterpreted value given a section, an optional subsection and value name, and if it passes filter.

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

pub fn raw_values(&self, key: impl AsKey) -> Result<Vec<Cow<'_, BStr>>, Error>

Returns all uninterpreted values given a key.

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

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.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 value does not support multi-valued values.

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

Returns all uninterpreted values given a section, an optional subsection and value name 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.

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_by("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 value name, if your value does not support multi-valued values.

pub fn raw_values_filter( &self, key: impl AsKey, filter: impl FnMut(&Metadata) -> bool, ) -> Result<Vec<Cow<'_, BStr>>, Error>

Returns all uninterpreted values given a 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 raw_values_filter_by( &self, section_name: impl AsRef<str>, subsection_name: Option<&BStr>, value_name: impl AsRef<str>, filter: impl FnMut(&Metadata) -> bool, ) -> Result<Vec<Cow<'_, BStr>>, Error>

Returns all uninterpreted values given a section, an optional subsection and value name, 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 raw_values_mut<'lookup>( &mut self, key: &'lookup impl AsKey, ) -> Result<MultiValueMut<'_, 'lookup, 'event>, Error>

Returns mutable references to all uninterpreted values given a 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.a")?,
    vec![
        Cow::<BStr>::Borrowed("b".into()),
        Cow::<BStr>::Borrowed("c".into()),
        Cow::<BStr>::Borrowed("d".into())
    ]
);

git_config.raw_values_mut(&"core.a")?.set_all("g");

assert_eq!(
    git_config.raw_values("core.a")?,
    vec![
        Cow::<BStr>::Borrowed("g".into()),
        Cow::<BStr>::Borrowed("g".into()),
        Cow::<BStr>::Borrowed("g".into())
    ],
);

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

Note that this operation is relatively expensive, requiring a full traversal of the config.

pub fn raw_values_mut_by<'lookup>( &mut self, section_name: impl AsRef<str>, subsection_name: Option<&'lookup BStr>, value_name: &'lookup str, ) -> Result<MultiValueMut<'_, 'lookup, 'event>, Error>

Returns mutable references to all uninterpreted values given a section, an optional subsection and value name.

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.a")?,
    vec![
        Cow::<BStr>::Borrowed("b".into()),
        Cow::<BStr>::Borrowed("c".into()),
        Cow::<BStr>::Borrowed("d".into())
    ]
);

git_config.raw_values_mut_by("core", None, "a")?.set_all("g");

assert_eq!(
    git_config.raw_values("core.a")?,
    vec![
        Cow::<BStr>::Borrowed("g".into()),
        Cow::<BStr>::Borrowed("g".into()),
        Cow::<BStr>::Borrowed("g".into())
    ],
);

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

Note that this operation is relatively expensive, requiring a full traversal of the config.

pub fn raw_values_mut_filter<'lookup>( &mut self, key: &'lookup impl AsKey, filter: impl FnMut(&Metadata) -> bool, ) -> Result<MultiValueMut<'_, 'lookup, 'event>, Error>

Returns mutable references to all uninterpreted values given a key, if their sections pass filter.

pub fn raw_values_mut_filter_by<'lookup>( &mut self, section_name: impl AsRef<str>, subsection_name: Option<&'lookup BStr>, value_name: &'lookup str, filter: impl FnMut(&Metadata) -> bool, ) -> Result<MultiValueMut<'_, 'lookup, 'event>, Error>

Returns mutable references to all uninterpreted values given a section, an optional subsection and value name, if their sections pass filter.

pub fn set_existing_raw_value<'b>( &mut self, key: &'b impl AsKey, new_value: impl Into<&'b BStr>, ) -> Result<(), Error>

Sets a value in a given key. Note that the parts leading to the value name must exist for this method to work, i.e. the section and the subsection, if present.

Examples

Given the config,

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

Setting a new value to the key core.a will yield the following:

git_config.set_existing_raw_value(&"core.a", "e")?;
assert_eq!(git_config.raw_value("core.a")?, Cow::<BStr>::Borrowed("e".into()));
assert_eq!(
    git_config.raw_values("core.a")?,
    vec![
        Cow::<BStr>::Borrowed("b".into()),
        Cow::<BStr>::Borrowed("c".into()),
        Cow::<BStr>::Borrowed("e".into())
    ],
);

pub fn set_existing_raw_value_by<'b>( &mut self, section_name: impl AsRef<str>, subsection_name: Option<&BStr>, value_name: impl AsRef<str>, new_value: impl Into<&'b BStr>, ) -> Result<(), Error>

Sets a value in a given section_name, optional subsection_name, and value_name. Note sections named section_name and subsection_name (if not None) must exist for this method to work.

Examples

Given the config,

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

Setting a new value to the key core.a will yield the following:

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

pub fn set_raw_value<'b>( &mut self, key: &'event impl AsKey, new_value: impl Into<&'b BStr>, ) -> Result<Option<Cow<'event, BStr>>, Error>

Sets a value in a given key. Creates the section if necessary and the value as well, or overwrites the last existing value otherwise.

Examples

Given the config,

[core]
    a = b

Setting a new value to the key core.a will yield the following:

let prev = git_config.set_raw_value(&"core.a", "e")?;
git_config.set_raw_value(&"core.b", "f")?;
assert_eq!(prev.expect("present").as_ref(), "b");
assert_eq!(git_config.raw_value("core.a")?, Cow::<BStr>::Borrowed("e".into()));
assert_eq!(git_config.raw_value("core.b")?, Cow::<BStr>::Borrowed("f".into()));

pub fn set_raw_value_by<'b, Key, E>( &mut self, section_name: impl AsRef<str>, subsection_name: Option<&BStr>, value_name: Key, new_value: impl Into<&'b BStr>, ) -> Result<Option<Cow<'event, BStr>>, Error>

where Key: TryInto<ValueName<'event>, Error = E>, Error: From<E>,

Sets a value in a given section_name, optional subsection_name, and value_name. Creates the section if necessary and the value as well, or overwrites the last existing value otherwise.

Examples

Given the config,

[core]
    a = b

Setting a new value to the key core.a will yield the following:

let prev = git_config.set_raw_value_by("core", None, "a", "e")?;
git_config.set_raw_value_by("core", None, "b", "f")?;
assert_eq!(prev.expect("present").as_ref(), "b");
assert_eq!(git_config.raw_value("core.a")?, Cow::<BStr>::Borrowed("e".into()));
assert_eq!(git_config.raw_value("core.b")?, Cow::<BStr>::Borrowed("f".into()));

pub fn set_raw_value_filter<'b>( &mut self, key: &'event impl AsKey, new_value: impl Into<&'b BStr>, filter: impl FnMut(&Metadata) -> bool, ) -> Result<Option<Cow<'event, BStr>>, Error>

Similar to set_raw_value(), but only sets existing values in sections matching filter, creating a new section otherwise.

pub fn set_raw_value_filter_by<'b, Key, E>( &mut self, section_name: impl AsRef<str>, subsection_name: Option<&BStr>, key: Key, new_value: impl Into<&'b BStr>, filter: impl FnMut(&Metadata) -> bool, ) -> Result<Option<Cow<'event, BStr>>, Error>

where Key: TryInto<ValueName<'event>, Error = E>, Error: From<E>,

Similar to set_raw_value_by(), but only sets existing values in sections matching filter, creating a new section otherwise.

pub fn set_existing_raw_multi_value<'a, Iter, Item>( &mut self, key: &'a impl AsKey, new_values: Iter, ) -> Result<(), Error>

where Iter: IntoIterator<Item = Item>, Item: Into<&'a BStr>,

Sets a multivar in a given key.

This internally zips together the new values and the existing values. As a result, if more new values are provided than the current amount of multivars, then the latter values are not applied. If there are less new values than old ones then the remaining old values are unmodified.

Note: Mutation order is not guaranteed and is non-deterministic. If you need finer control over which values of the multivar are set, consider using raw_values_mut(), which will let you iterate and check over the values instead. This is best used as a convenience function for setting multivars whose values should be treated as an unordered set.

Examples

Let us use the follow config for all examples:

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

Setting an equal number of values:

let new_values = vec![
    "x",
    "y",
    "z",
];
git_config.set_existing_raw_multi_value(&"core.a", new_values.into_iter())?;
let fetched_config = git_config.raw_values("core.a")?;
assert!(fetched_config.contains(&Cow::<BStr>::Borrowed("x".into())));
assert!(fetched_config.contains(&Cow::<BStr>::Borrowed("y".into())));
assert!(fetched_config.contains(&Cow::<BStr>::Borrowed("z".into())));

Setting less than the number of present values sets the first ones found:

let new_values = vec![
    "x",
    "y",
];
git_config.set_existing_raw_multi_value(&"core.a", new_values.into_iter())?;
let fetched_config = git_config.raw_values("core.a")?;
assert!(fetched_config.contains(&Cow::<BStr>::Borrowed("x".into())));
assert!(fetched_config.contains(&Cow::<BStr>::Borrowed("y".into())));

Setting more than the number of present values discards the rest:

let new_values = vec![
    "x",
    "y",
    "z",
    "discarded",
];
git_config.set_existing_raw_multi_value(&"core.a", new_values)?;
assert!(!git_config.raw_values("core.a")?.contains(&Cow::<BStr>::Borrowed("discarded".into())));

pub fn set_existing_raw_multi_value_by<'a, Iter, Item>( &mut self, section_name: impl AsRef<str>, subsection_name: Option<&BStr>, value_name: impl AsRef<str>, new_values: Iter, ) -> Result<(), Error>

where Iter: IntoIterator<Item = Item>, Item: Into<&'a BStr>,

Sets a multivar in a given section, optional subsection, and key value.

This internally zips together the new values and the existing values. As a result, if more new values are provided than the current amount of multivars, then the latter values are not applied. If there are less new values than old ones then the remaining old values are unmodified.

Note: Mutation order is not guaranteed and is non-deterministic. If you need finer control over which values of the multivar are set, consider using raw_values_mut(), which will let you iterate and check over the values instead. This is best used as a convenience function for setting multivars whose values should be treated as an unordered set.

Examples

Let us use the follow config for all examples:

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

Setting an equal number of values:

let new_values = vec![
    "x",
    "y",
    "z",
];
git_config.set_existing_raw_multi_value_by("core", None, "a", new_values.into_iter())?;
let fetched_config = git_config.raw_values("core.a")?;
assert!(fetched_config.contains(&Cow::<BStr>::Borrowed("x".into())));
assert!(fetched_config.contains(&Cow::<BStr>::Borrowed("y".into())));
assert!(fetched_config.contains(&Cow::<BStr>::Borrowed("z".into())));

Setting less than the number of present values sets the first ones found:

let new_values = vec![
    "x",
    "y",
];
git_config.set_existing_raw_multi_value_by("core", None, "a", new_values.into_iter())?;
let fetched_config = git_config.raw_values("core.a")?;
assert!(fetched_config.contains(&Cow::<BStr>::Borrowed("x".into())));
assert!(fetched_config.contains(&Cow::<BStr>::Borrowed("y".into())));

Setting more than the number of present values discards the rest:

let new_values = vec![
    "x",
    "y",
    "z",
    "discarded",
];
git_config.set_existing_raw_multi_value_by("core", None, "a", new_values)?;
assert!(!git_config.raw_values("core.a")?.contains(&Cow::<BStr>::Borrowed("discarded".into())));

impl<'event> File<'event>

Read-only low-level access methods, as it requires generics for converting into custom values defined in this crate like Integer and Color.

pub fn value<'a, T: TryFrom<Cow<'a, BStr>>>( &'a self, key: impl AsKey, ) -> Result<T, Error<T::Error>>

Returns an interpreted value given a 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 = gix_config::File::try_from(config)?;
// You can either use the turbofish to determine the type...
let a_value = git_config.value::<Integer>("core.a")?;
// ... or explicitly declare the type to avoid the turbofish
let c_value: Boolean = git_config.value("core.c")?;

pub fn value_by<'a, T: TryFrom<Cow<'a, BStr>>>( &'a self, section_name: &str, subsection_name: Option<&BStr>, value_name: &str, ) -> Result<T, Error<T::Error>>

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

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 = gix_config::File::try_from(config)?;
// You can either use the turbofish to determine the type...
let a_value = git_config.value_by::<Integer>("core", None, "a")?;
// ... or explicitly declare the type to avoid the turbofish
let c_value: Boolean = git_config.value_by("core", None, "c")?;

pub fn try_value<'a, T: TryFrom<Cow<'a, BStr>>>( &'a self, key: impl AsKey, ) -> Option<Result<T, T::Error>>

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

pub fn try_value_by<'a, T: TryFrom<Cow<'a, BStr>>>( &'a self, section_name: &str, subsection_name: Option<&BStr>, value_name: &str, ) -> Option<Result<T, T::Error>>

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

pub fn values<'a, T: TryFrom<Cow<'a, BStr>>>( &'a self, key: impl AsKey, ) -> Result<Vec<T>, Error<T::Error>>

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

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 = gix_config::File::try_from(config).unwrap();
// You can either use the turbofish to determine the type...
let a_value = git_config.values::<Boolean>("core.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.c").unwrap();
assert_eq!(c_value, vec![Boolean(false)]);

pub fn values_by<'a, T: TryFrom<Cow<'a, BStr>>>( &'a self, section_name: &str, subsection_name: Option<&BStr>, value_name: &str, ) -> Result<Vec<T>, Error<T::Error>>

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

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 = gix_config::File::try_from(config).unwrap();
// You can either use the turbofish to determine the type...
let a_value = git_config.values_by::<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_by("core", None, "c").unwrap();
assert_eq!(c_value, vec![Boolean(false)]);

pub fn section( &self, name: &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( &self, section_key: &BStr, ) -> Result<&Section<'event>, Error>

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

pub fn section_filter<'a>( &'a self, name: &str, subsection_name: Option<&BStr>, filter: impl FnMut(&Metadata) -> bool, ) -> 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<'a>( &'a self, section_key: &BStr, filter: impl FnMut(&Metadata) -> bool, ) -> Result<Option<&'a Section<'event>>, Error>

Like section_filter(), but identifies the section with section_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 = gix_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: impl FnMut(&Metadata) -> bool + 'a, ) -> 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 this file’s metadata, typically set when it was first created to indicate its origins.

It will be used in all newly created sections to identify them. Change it with File::set_meta().

pub fn set_meta(&mut self, meta: impl Into<OwnShared<Metadata>>) -> &mut Self

Change the origin of this instance to be the given metadata.

This is useful to control what origin about-to-be-added sections receive.

pub fn meta_owned(&self) -> OwnShared<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>>)>

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.

impl File<'static>

pub fn resolve_includes(&mut self, options: Options<'_>) -> Result<(), Error>

Traverse all include and includeIf directives found in this instance and follow them, loading the referenced files from their location and adding their content right past the value that included them.

Limitations

• Note that this method is not idempotent and calling it multiple times will resolve includes multiple times. It’s recommended use is as part of a multi-step bootstrapping which needs fine-grained control, and unless that’s given one should prefer one of the other ways of initialization that resolve includes at the right time.

Deviation

• included values are added after the section that included them, not directly after the value. This is a deviation from how git does it, as it technically adds new value right after the include path itself, technically ‘splitting’ the section. This can only make a difference if the include section also has values which later overwrite portions of the included file, which seems unusual as these would be related to includes. We can fix this by ‘splitting’ the include section if needed so the included sections are put into the right place.
• hasconfig:remote.*.url will not prevent itself to include files with [remote "name"]\nurl = x values, but it also won’t match them, i.e. one cannot include something that will cause the condition to match or to always be true.

impl File<'_>

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_filter( &self, out: &mut dyn Write, filter: impl FnMut(&Section<'_>) -> bool, ) -> Result<()>

Stream ourselves to the given out in order to reproduce this file mostly losslessly as it was parsed, while writing only sections for which filter returns true.

pub fn write_to(&self, out: &mut dyn Write) -> Result<()>

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

Trait Implementations

impl<'event> Clone for File<'event>

fn clone(&self) -> File<'event>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'event> Debug for File<'event>

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

Formats the value using the given formatter.

impl<'event> Default for File<'event>

fn default() -> File<'event>

Returns the “default value” for a type.

impl Display for File<'_>

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

Formats the value using the given formatter.

impl From<File<'_>> for BString

fn from(c: File<'_>) -> Self

Converts to this type from the input type.

impl FromStr for File<'static>

type Err = Error

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl PartialEq for File<'_>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> TryFrom<&'a BStr> for File<'a>

fn try_from(value: &'a BStr) -> Result<File<'a>, Self::Error>

Convenience constructor. Attempts to parse the provided byte string into a File. See Events::from_bytes() for more information.

type Error = Error

The type returned in the event of a conversion error.

impl<'a> TryFrom<&'a str> for File<'a>

fn try_from(s: &'a str) -> Result<File<'a>, Self::Error>

Convenience constructor. Attempts to parse the provided string into a File. See Events::from_str() for more information.

type Error = Error

The type returned in the event of a conversion error.

impl<'event> Eq for File<'event>