Struct ConfigFile 

pub struct ConfigFile {
    pub path: PathBuf,
    pub scope: ConfigScope,
    pub entries: Vec<ConfigEntry>,
    pub include_origin: ConfigIncludeOrigin,
    /* private fields */
}

A parsed configuration file that preserves the raw text for round-trip editing (set/unset/rename-section/remove-section).

Fields

path: PathBuf

The path to this config file on disk.

scope: ConfigScope

The scope this file represents.

entries: Vec<ConfigEntry>

Parsed entries (in file order).

include_origin: ConfigIncludeOrigin

Source kind for [include] resolution (Git CONFIG_ORIGIN_*).

Implementations

impl ConfigFile

pub fn parse(path: &Path, content: &str, scope: ConfigScope) -> Result<Self>

Parse a config file from its raw text content.

Parameters

• path — the file path (stored for diagnostics and round-trip writes).
• content — the raw text of the file.
• scope — the ConfigScope this file represents.

Errors

Returns Error::Config on malformed input.

pub fn parse_gitmodules_best_effort( path: &Path, content: &str, scope: ConfigScope, ) -> (Vec<ConfigEntry>, Option<usize>)

Like Self::parse for .gitmodules, but on an unclosed-quote / bad line returns entries parsed before that line plus the one-based line number of the bad logical line.

Git streams config and still applies entries from valid preceding lines; submodule-config tests rely on that when a later .gitmodules line is malformed.

pub fn get(&self, key: &str) -> Option<String>

Last value for key in this file only (canonical key, case-insensitive section/var like Git).

pub fn parse_with_origin( path: &Path, content: &str, scope: ConfigScope, include_origin: ConfigIncludeOrigin, ) -> Result<Self>

Parse like Self::parse but record a non-disk include origin (blob, stdin, command line).

pub fn from_git_config_parameters(path: &Path, raw: &str) -> Result<Self>

Build a synthetic ConfigFile from GIT_CONFIG_PARAMETERS / git -c payloads.

Unlike Self::parse, this accepts flat key=value assignments without [section] headers, matching how Git injects command-line configuration.

pub fn from_path(path: &Path, scope: ConfigScope) -> Result<Option<Self>>

Read and parse a config file from disk.

Returns Ok(None) if the file does not exist.

Errors

Returns Error::Io on read failure (other than not-found) or Error::Config on parse failure.

pub fn set(&mut self, key: &str, value: &str) -> Result<()>

Set a value in this config file, creating the section if needed.

If the key already exists, its last occurrence is updated in-place. Otherwise a new entry is appended (creating the section header if necessary).

Parameters

• key — canonical key (e.g. core.bare).
• value — the value to set.

pub fn set_with_comment( &mut self, key: &str, value: &str, comment: Option<&str>, ) -> Result<()>

Set a value in this config file, optionally appending an inline comment.

pub fn replace_all( &mut self, key: &str, value: &str, value_pattern: Option<&str>, ) -> Result<()>

Replace ALL occurrences of a key with a new value.

Removes all but the last occurrence from the file, then updates the last occurrence with the new value (matching Git behaviour).

pub fn replace_all_with_comment( &mut self, key: &str, value: &str, value_pattern: Option<&str>, comment: Option<&str>, ) -> Result<()>

Replace all occurrences, optionally appending an inline comment.

Value patterns starting with ! are treated as negated regex (matching values that do NOT match the pattern).

pub fn count(&self, key: &str) -> Result<usize>

Count how many entries exist for a key.

pub fn unset_last(&mut self, key: &str) -> Result<usize>

Unset (remove) only the last occurrence of a key.

Returns the number of entries removed (0 or 1).

pub fn unset(&mut self, key: &str) -> Result<usize>

Unset (remove) all occurrences of a key.

Parameters

• key — canonical key (e.g. core.bare).

Returns

The number of entries removed.

pub fn unset_matching( &mut self, key: &str, value_pattern: Option<&str>, preserve_empty_section_header: bool, ) -> Result<usize>

Unset entries matching a key and optional value-pattern regex.

If value_pattern is None, removes all entries with the given key. If value_pattern is Some(pat), only removes entries whose value matches the regex.

When preserve_empty_section_header is true, a section header is kept even if the section has no remaining keys (Git’s config unset --all). When false, empty sections are stripped (config --unset, config --unset-all, and value-pattern unsets).

pub fn remove_section(&mut self, section: &str) -> Result<bool>

Remove an entire section (and all its entries).

Parameters

• section — section name (e.g. "core", "remote.origin").

pub fn rename_section(&mut self, old_name: &str, new_name: &str) -> Result<bool>

Rename a section.

Parameters

• old_name — current section name (e.g. "branch.main").
• new_name — new section name (e.g. "branch.develop").

pub fn add_value(&mut self, key: &str, value: &str) -> Result<()>

Append a new value for a key without removing existing entries.

This is the behaviour of git config --add section.key value. If the section doesn’t exist, it is created.

pub fn add_value_with_comment( &mut self, key: &str, value: &str, comment: Option<&str>, ) -> Result<()>

Append a new value with an optional inline comment.

pub fn write(&self) -> Result<()>

Write the file back to Self::path through {path}.lock and an atomic rename.

The existing file’s permission bits are kept. Like Git, which has no core.fsync component for config files, the lock file is not fsynced before the rename: readers always see either the old or the new file, but a crash may lose the update.

Errors

Returns Error::Io on write failure, or ConfigError::ConfigFileLocked when {path}.lock already exists.

Trait Implementations

impl Clone for ConfigFile

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ConfigFile

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

Formats the value using the given formatter.