Enum git_config::Source

pub enum Source {
    GitInstallation,
    System,
    Git,
    User,
    Local,
    Worktree,
    Env,
    Cli,
    Api,
    EnvOverride,
}

A list of known sources for git configuration in order of ascending precedence.

This means values from the first one will be overridden by values in the second one, and so forth. Note that included files via include.path and includeIf.<condition>.path inherit their source.

Variants

GitInstallation

A special configuration file that ships with the git installation, and is thus tied to the used git binary.

System

System-wide configuration path. This is defined as $(prefix)/etc/gitconfig (where prefix is the git-installation directory).

Git

A platform defined location for where a user’s git application configuration should be located. If $XDG_CONFIG_HOME is not set or empty, $HOME/.config/git/config will be used on unix.

User

This is usually ~/.gitconfig on unix.

Local

The configuration of the repository itself, located in .git/config.

Worktree

Configuration specific to a worktree as created with git worktree and typically located in $GIT_DIR/config.worktree if extensions.worktreeConfig is enabled.

Env

Values parsed from the environment using GIT_CONFIG_COUNT, GIT_CONFIG_KEY_N and GIT_CONFIG_VALUE_N where N is incremented from 0 up to the value of GIT_CONFIG_COUNT.

Cli

Values set from the command-line, typically controlled by the user running a program.

Api

Entirely internal from a programmatic source, and can be used to have (near final) say in configuration values.

EnvOverride

Values obtained from specific environment variables that override values in the git configuration.

For example, HTTP_PROXY overrides http.proxy, no matter where it is specified, and thus controls the value similar to how it’s done in git.

Implementations

impl Source

pub const fn kind(self) -> Kind

Return true if the source indicates a location within a file of a repository.

Examples found in repository

src/source.rs (line 35)

    pub fn sources(self) -> &'static [Source] {
        let src = match self {
            Kind::GitInstallation => &[Source::GitInstallation] as &[_],
            Kind::System => &[Source::System],
            Kind::Global => &[Source::Git, Source::User],
            Kind::Repository => &[Source::Local, Source::Worktree],
            Kind::Override => &[Source::Env, Source::Cli, Source::Api],
        };
        debug_assert!(
            src.iter().all(|src| src.kind() == self),
            "BUG: classification of source has to match the ordering here, see `Source::kind()`"
        );
        src
    }

pub fn storage_location(
    self,
    env_var: &mut dyn FnMut(&str) -> Option<OsString>
) -> Option<Cow<'static, Path>>

Returns the location at which a file of this type would be stored, or None if there is no notion of persistent storage for this source, with env_var to obtain environment variables. Note that the location can be relative for repository-local sources like Local and Worktree, and the caller has to known which base it it relative to, namely the common_dir in the Local case and the git_dir in the Worktree case. Be aware that depending on environment overrides, multiple scopes might return the same path, which should only be loaded once nonetheless.

With env_var it becomes possible to prevent accessing environment variables entirely to comply with git-sec permissions for example.

Examples found in repository

src/file/init/comfort.rs (line 33)

    pub fn from_globals() -> Result<File<'static>, init::from_paths::Error> {
        let metas = [source::Kind::System, source::Kind::Global]
            .iter()
            .flat_map(|kind| kind.sources())
            .filter_map(|source| {
                let path = source
                    .storage_location(&mut |name| std::env::var_os(name))
                    .and_then(|p| p.is_file().then(|| p))
                    .map(|p| p.into_owned());

                Metadata {
                    path,
                    source: *source,
                    level: 0,
                    trust: git_sec::Trust::Full,
                }
                .into()
            });

        let home = std::env::var("HOME").ok().map(PathBuf::from);
        let options = init::Options {
            includes: init::includes::Options::follow_without_conditional(home.as_deref()),
            ..Default::default()
        };
        File::from_paths_metadata(metas, options).map(Option::unwrap_or_default)
    }

    /// Generates a config from `GIT_CONFIG_*` environment variables and return a possibly empty `File`.
    /// A typical use of this is to [`append`][File::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.
    ///
    /// [`git-config`'s documentation]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-GITCONFIGCOUNT
    pub fn from_environment_overrides() -> Result<File<'static>, init::from_env::Error> {
        let home = std::env::var("HOME").ok().map(PathBuf::from);
        let options = init::Options {
            includes: init::includes::Options::follow_without_conditional(home.as_deref()),
            ..Default::default()
        };

        File::from_env(options).map(Option::unwrap_or_default)
    }
}

/// An easy way to provide complete configuration for a repository.
impl File<'static> {
    /// 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.
    pub fn from_git_dir(dir: impl Into<std::path::PathBuf>) -> Result<File<'static>, from_git_dir::Error> {
        let (mut local, git_dir) = {
            let source = Source::Local;
            let mut path = dir.into();
            path.push(
                source
                    .storage_location(&mut |n| std::env::var_os(n))
                    .expect("location available for local"),
            );
            let local = Self::from_path_no_includes(&path, source)?;
            path.pop();
            (local, path)
        };

        let worktree = match local.boolean("extensions", None, "worktreeConfig") {
            Some(Ok(worktree_config)) => worktree_config.then(|| {
                let source = Source::Worktree;
                let path = git_dir.join(
                    source
                        .storage_location(&mut |n| std::env::var_os(n))
                        .expect("location available for worktree"),
                );
                Self::from_path_no_includes(path, source)
            }),
            _ => None,
        }
        .transpose()?;

        let home = std::env::var("HOME").ok().map(PathBuf::from);
        let options = init::Options {
            includes: init::includes::Options::follow(
                path::interpolate::Context {
                    home_dir: home.as_deref(),
                    ..Default::default()
                },
                init::includes::conditional::Context {
                    git_dir: Some(git_dir.as_ref()),
                    branch_name: None,
                },
            ),
            lossy: false,
        };

        let mut globals = Self::from_globals()?;
        globals.resolve_includes(options)?;
        local.resolve_includes(options)?;

        globals.append(local);
        if let Some(mut worktree) = worktree {
            worktree.resolve_includes(options)?;
            globals.append(worktree);
        }
        globals.append(Self::from_environment_overrides()?);

        Ok(globals)
    }

Trait Implementations

impl Clone for Source

fn clone(&self) -> Source

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Source

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

Formats the value using the given formatter.

impl From<Source> for Metadata

fn from(source: Source) -> Self

Converts to this type from the input type.

impl Hash for Source

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where
    H: Hasher,
    Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Source

fn cmp(&self, other: &Source) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere
    Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere
    Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere
    Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl PartialEq<Source> for Source

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

This method tests for self and other values to be equal, and is used by ==.

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

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

impl PartialOrd<Source> for Source

fn partial_cmp(&self, other: &Source) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for Source

impl Eq for Source

impl StructuralEq for Source

impl StructuralPartialEq for Source