Struct Options

pub struct Options {
    pub permissions: Permissions,
    /* private fields */
}

The options used in ThreadSafeRepository::open_opts().

Replacement Objects for the object database

The environment variables GIT_REPLACE_REF_BASE and GIT_NO_REPLACE_OBJECTS are mapped to gitoxide.objects.replaceRefBase and gitoxide.objects.noReplace respectively and then interpreted exactly as their environment variable counterparts.

Use Permissions to control which environment variables can be read, and config-overrides to control these values programmatically.

Fields

permissions: Permissions

Define what is allowed while opening a repository.

Implementations

impl Options

Instantiation

pub fn isolated() -> Self

Options configured to prevent accessing anything else than the repository configuration file, prohibiting accessing the environment or spreading beyond the git repository location.

impl Options

Generic modification

pub fn modify(&mut self, f: impl FnOnce(Self) -> Self)

An adapter to allow calling any builder method on this instance despite only having a mutable reference.

impl Options

Builder methods

pub fn config_overrides( self, values: impl IntoIterator<Item = impl Into<BString>>, ) -> Self

Apply the given configuration values like init.defaultBranch=special or core.bool-implicit-true in memory to as early as the configuration is initialized to allow affecting the repository instantiation phase, both on disk or when opening. The configuration is marked with source API.

pub fn cli_overrides( self, values: impl IntoIterator<Item = impl Into<BString>>, ) -> Self

Set configuration values of the form core.abbrev=5 or remote.origin.url = foo or core.bool-implicit-true for application as CLI overrides to the repository configuration, marked with source CLI. These are equivalent to CLI overrides passed with -c in git, for example.

pub fn object_store_slots(self, slots: Slots) -> Self

Set the amount of slots to use for the object database. It’s a value that doesn’t need changes on the client, typically, but should be controlled on the server.

pub fn permissions(self, permissions: Permissions) -> Self

Set the given permissions, which are typically derived by a Trust level.

pub fn open_path_as_is(self, enable: bool) -> Self

If true, default false, we will not modify the incoming path to open to assure it is a .git directory.

If false, we will try to open the input directory as is, even though it doesn’t appear to be a git repository due to the lack of .git suffix or because its basename is not .git as in worktree/.git.

pub fn with(self, trust: Trust) -> Self

Set the trust level of the .git directory we are about to open.

This can be set manually to force trust even though otherwise it might not be fully trusted, leading to limitations in how configuration files are interpreted.

If not called explicitly, it will be determined by looking at its ownership via gix_sec::Trust::from_path_ownership().

Security Warning

Use with extreme care and only if it’s absolutely known that the repository is always controlled by the desired user. Using this capability only saves a permission check and only so if the open() method is used, as opposed to discovery.

pub fn bail_if_untrusted(self, toggle: bool) -> Self

If true, default false, and if the repository’s trust level is not Full (see with() for more), then the open operation will fail.

Use this to mimic gits way of handling untrusted repositories. Note that gitoxide solves this by not using configuration from untrusted sources and by generally being secured against doctored input files which at worst could cause out-of-memory at the time of writing.

pub fn filter_config_section(self, filter: fn(_: &Metadata) -> bool) -> Self

Set the filter which determines if a configuration section can be used to read values from, hence it returns true if it is eligible.

The default filter selects sections whose trust level is full or whose source is not repository-local.

pub fn lossy_config(self, toggle: bool) -> Self

By default, in release mode configuration will be read without retaining non-essential information like comments or whitespace to optimize lookup performance.

Some application might want to toggle this to false in they want to display or edit configuration losslessly with all whitespace and comments included.

pub fn strict_config(self, toggle: bool) -> Self

If set, default is false, invalid configuration values will cause an error even if these can safely be defaulted.

This is recommended for all applications that prefer correctness over usability. git itself defaults to strict configuration mode, flagging incorrect configuration immediately.

Failure to read configuration files due to IO errors will also be a hard error if this mode is enabled, otherwise these errors will merely be logged.

pub fn open( self, path: impl Into<PathBuf>, ) -> Result<ThreadSafeRepository, Error>

Open a repository at path with the options set so far.

Trait Implementations

impl Clone for Options

fn clone(&self) -> Options

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for Options

fn default() -> Self

Returns the “default value” for a type.

impl DefaultForLevel for Options

fn default_for_level(level: Trust) -> Self

Produce a default value for the given trust level.