Struct gix::ThreadSafeRepository

pub struct ThreadSafeRepository {
    pub refs: RefStore,
    pub objects: OwnShared<Store>,
    pub work_tree: Option<PathBuf>,
    pub common_dir: Option<PathBuf>,
    /* private fields */
}

An instance with access to everything a git repository entails, best imagined as container implementing Sync + Send for most for system resources required to interact with a git repository which are loaded in once the instance is created.

Use this type to reference it in a threaded context for creation the creation of a thread-local Repositories.

Note that this type purposefully isn’t very useful until it is converted into a thread-local repository with to_thread_local(), it’s merely meant to be able to exist in a Sync context.

Note that it can also cheaply be cloned, and it will retain references to all contained resources.

Fields

refs: RefStore

A store for references to point at objects

objects: OwnShared<Store>

A store for objects that contain data

work_tree: Option<PathBuf>

The path to the worktree at which to find checked out files

common_dir: Option<PathBuf>

The path to the common directory if this is a linked worktree repository or it is otherwise set.

Implementations

impl ThreadSafeRepository

pub fn to_thread_local(&self) -> Repository

Add thread-local state to an easy-to-use thread-local repository for the most convenient API.

impl ThreadSafeRepository

pub fn path(&self) -> &Path

The path to the .git directory itself, or equivalent if this is a bare repository.

pub fn git_dir(&self) -> &Path

Return the path to the repository itself, containing objects, references, configuration, and more.

Synonymous to path().

pub fn work_dir(&self) -> Option<&Path>

Return the path to the working directory if this is not a bare repository.

pub fn objects_dir(&self) -> &Path

Return the path to the directory containing all objects.

impl ThreadSafeRepository

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

Open a git repository at the given path, possibly expanding it to path/.git if path is a work tree dir.

pub fn open_opts( path: impl Into<PathBuf>, options: Options ) -> Result<Self, Error>

Open a git repository at the given path, possibly expanding it to path/.git if path is a work tree dir, and use options for fine-grained control.

Note that you should use crate::discover() if security should be adjusted by ownership.

Differences to git2::Repository::open_ext()

Whereas open_ext() is the jack-of-all-trades that can do anything depending on its options, gix will always differentiate between discovering git repositories by searching, and opening a well-known repository by work tree or .git repository.

Note that opening a repository for implementing custom hooks is also handle specifically in open_with_environment_overrides().

pub fn open_with_environment_overrides( fallback_directory: impl Into<PathBuf>, trust_map: Mapping<Options> ) -> Result<Self, Error>

Try to open a git repository in fallback_directory (can be worktree or .git directory) only if there is no override from of the gitdir using git environment variables.

Use the trust_map to apply options depending in the trust level for directory or the directory it’s overridden with. The .git directory whether given or computed is used for trust checks.

Note that this will read various GIT_* environment variables to check for overrides, and is probably most useful when implementing custom hooks.

impl ThreadSafeRepository

pub fn init( directory: impl AsRef<Path>, kind: Kind, options: Options ) -> Result<Self, Error>

Create a repository with work-tree within directory, creating intermediate directories as needed.

Fails without action if there is already a .git repository inside of directory, but won’t mind if the directory otherwise is non-empty.

pub fn init_opts( directory: impl AsRef<Path>, kind: Kind, create_options: Options, open_options: Options ) -> Result<Self, Error>

Similar to init, but allows to determine how exactly to open the newly created repository.

Deviation

Instead of naming the default branch master, we name it main unless configured explicitly using the init.defaultBranch configuration key.

impl ThreadSafeRepository

pub fn discover(directory: impl AsRef<Path>) -> Result<Self, Error>

Try to open a git repository in directory and search upwards through its parents until one is found, using default trust options which matters in case the found repository isn’t owned by the current user.

pub fn discover_opts( directory: impl AsRef<Path>, options: Options<'_>, trust_map: Mapping<Options> ) -> Result<Self, Error>

Try to open a git repository in directory and search upwards through its parents until one is found, while applying options. Then use the trust_map to determine which of our own repository options to use for instantiations.

Note that trust overrides in the trust_map are not effective here and we will always override it with the determined trust value. This is a precaution as the API user is unable to actually know if the directory that is discovered can indeed be trusted (or else they’d have to implement the discovery themselves and be sure that no attacker ever gets access to a directory structure. The cost of this is a permission check, which seems acceptable).

pub fn discover_with_environment_overrides( directory: impl AsRef<Path> ) -> Result<Self, Error>

Try to open a git repository directly from the environment. If that fails, discover upwards from directory until one is found, while applying discovery options from the environment.

pub fn discover_with_environment_overrides_opts( directory: impl AsRef<Path>, options: Options<'_>, trust_map: Mapping<Options> ) -> Result<Self, Error>

Try to open a git repository directly from the environment, which reads GIT_DIR if it is set. If unset, discover upwards from directory until one is found, while applying options with overrides from the environment which includes:

• GIT_DISCOVERY_ACROSS_FILESYSTEM
• GIT_CEILING_DIRECTORIES

Finally, use the trust_map to determine which of our own repository options to use based on the trust level of the effective repository directory.

Trait Implementations

impl Clone for ThreadSafeRepository

fn clone(&self) -> ThreadSafeRepository

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ThreadSafeRepository

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

Formats the value using the given formatter.

impl From<&ThreadSafeRepository> for Repository

fn from(repo: &ThreadSafeRepository) -> Self

Converts to this type from the input type.

impl From<Repository> for ThreadSafeRepository

fn from(r: Repository) -> Self

Converts to this type from the input type.

impl From<ThreadSafeRepository> for Repository

fn from(repo: ThreadSafeRepository) -> Self

Converts to this type from the input type.

impl PartialEq<ThreadSafeRepository> for ThreadSafeRepository

fn eq(&self, other: &ThreadSafeRepository) -> 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.