Struct gix::Repository
source · pub struct Repository {
pub refs: RefStore,
pub objects: OdbHandle,
/* private fields */
}
Expand description
A thread-local handle to interact with a repository from a single thread.
It is Send
but not Sync
- for the latter you can convert it to_sync()
.
Note that it clones itself so that it is empty, requiring the user to configure each clone separately, specifically
and explicitly. This is to have the fastest-possible default configuration available by default, but allow
those who experiment with workloads to get speed boosts of 2x or more.
Fields§
§refs: RefStore
A ref store with shared ownership (or the equivalent of it).
objects: OdbHandle
A way to access objects.
Implementations§
source§impl Repository
impl Repository
sourcepub fn attributes(
&self,
index: &State,
attributes_source: Source,
ignore_source: Source,
exclude_overrides: Option<Search>
) -> Result<AttributeStack<'_>, Error>
Available on (crate features attributes
or excludes
) and crate feature attributes
only.
pub fn attributes( &self, index: &State, attributes_source: Source, ignore_source: Source, exclude_overrides: Option<Search> ) -> Result<AttributeStack<'_>, Error>
attributes
or excludes
) and crate feature attributes
only.Configure a file-system cache for accessing git attributes and excludes on a per-path basis.
Use attribute_source
to specify where to read attributes from. Also note that exclude information will
always try to read .gitignore
files from disk before trying to read it from the index
.
Note that no worktree is required for this to work, even though access to in-tree .gitattributes
and .gitignore
files
would require a non-empty index
that represents a git tree.
This takes into consideration all the usual repository configuration, namely:
$XDG_CONFIG_HOME/…/ignore|attributes
ifcore.excludesFile|attributesFile
is not set, otherwise use the configured file.$GIT_DIR/info/exclude|attributes
if present.
sourcepub fn attributes_only(
&self,
index: &State,
attributes_source: Source
) -> Result<AttributeStack<'_>, Error>
Available on (crate features attributes
or excludes
) and crate feature attributes
only.
pub fn attributes_only( &self, index: &State, attributes_source: Source ) -> Result<AttributeStack<'_>, Error>
attributes
or excludes
) and crate feature attributes
only.Like attributes(), but without access to exclude/ignore information.
sourcepub fn excludes(
&self,
index: &State,
overrides: Option<Search>,
source: Source
) -> Result<AttributeStack<'_>, Error>
Available on (crate features attributes
or excludes
) and crate feature excludes
only.
pub fn excludes( &self, index: &State, overrides: Option<Search>, source: Source ) -> Result<AttributeStack<'_>, Error>
attributes
or excludes
) and crate feature excludes
only.Configure a file-system cache checking if files below the repository are excluded, reading .gitignore
files from
the specified source
.
Note that no worktree is required for this to work, even though access to in-tree .gitignore
files would require
a non-empty index
that represents a tree with .gitignore
files.
This takes into consideration all the usual repository configuration, namely:
$XDG_CONFIG_HOME/…/ignore
ifcore.excludesFile
is not set, otherwise use the configured file.$GIT_DIR/info/exclude
if present.
When only excludes are desired, this is the most efficient way to obtain them. Otherwise use
Repository::attributes()
for accessing both attributes and excludes.
source§impl Repository
impl Repository
Configure how caches are used to speed up various git repository operations
sourcepub fn object_cache_size(&mut self, bytes: impl Into<Option<usize>>)
pub fn object_cache_size(&mut self, bytes: impl Into<Option<usize>>)
Sets the amount of space used at most for caching most recently accessed fully decoded objects, to Some(bytes)
,
or None
to deactivate it entirely.
Note that it is unset by default but can be enabled once there is time for performance optimization. Well-chosen cache sizes can improve performance particularly if objects are accessed multiple times in a row. The cache is configured to grow gradually.
Note that a cache on application level should be considered as well as the best object access is not doing one.
sourcepub fn object_cache_size_if_unset(&mut self, bytes: usize)
pub fn object_cache_size_if_unset(&mut self, bytes: usize)
Set an object cache of size bytes
if none is set.
Use this method to avoid overwriting any existing value while assuring better performance in case no value is set.
source§impl Repository
impl Repository
sourcepub fn transport_options<'a>(
&self,
url: impl Into<&'a BStr>,
remote_name: Option<&BStr>
) -> Result<Option<Box<dyn Any>>, Error>
Available on crate features blocking-network-client
or async-network-client
only.
pub fn transport_options<'a>( &self, url: impl Into<&'a BStr>, remote_name: Option<&BStr> ) -> Result<Option<Box<dyn Any>>, Error>
blocking-network-client
or async-network-client
only.Produce configuration suitable for url
, as differentiated by its protocol/scheme, to be passed to a transport instance via
configure() (via &**config
to pass the contained Any
and not the Box
).
None
is returned if there is no known configuration. If remote_name
is not None
, the remote’s name may contribute to
configuration overrides, typically for the HTTP transport.
Note that the caller may cast the instance themselves to modify it before passing it on.
For transports that support proxy authentication, the default authentication method will be used with the url of the proxy if it contains a user name.
source§impl Repository
impl Repository
sourcepub fn remote_names(&self) -> BTreeSet<&str>
pub fn remote_names(&self) -> BTreeSet<&str>
Returns a sorted list unique of symbolic names of remotes that we deem trustworthy.
sourcepub fn remote_default_name(&self, direction: Direction) -> Option<Cow<'_, str>>
pub fn remote_default_name(&self, direction: Direction) -> Option<Cow<'_, str>>
Obtain the branch-independent name for a remote for use in the given direction
, or None
if it could not be determined.
For fetching, use the only configured remote, or default to origin
if it exists.
For pushing, use the remote.pushDefault
trusted configuration key, or fall back to the rules for fetching.
Notes
It’s up to the caller to determine what to do if the current head
is unborn or detached.
source§impl Repository
impl Repository
sourcepub fn branch_names(&self) -> BTreeSet<&str>
pub fn branch_names(&self) -> BTreeSet<&str>
Return a set of unique short branch names for which custom configuration exists in the configuration, if we deem them trustworthy.
sourcepub fn branch_remote_ref<'a>(
&self,
short_branch_name: impl Into<&'a BStr>
) -> Option<Result<Cow<'_, FullNameRef>, ValidateNameError>>
pub fn branch_remote_ref<'a>( &self, short_branch_name: impl Into<&'a BStr> ) -> Option<Result<Cow<'_, FullNameRef>, ValidateNameError>>
Returns the validated reference on the remote associated with the given short_branch_name
,
always main
instead of refs/heads/main
.
The returned reference is the one we track on the remote side for merging and pushing.
Returns None
if the remote reference was not found.
May return an error if the reference is invalid.
sourcepub fn branch_remote_name<'a>(
&self,
short_branch_name: impl Into<&'a BStr>
) -> Option<Name<'_>>
pub fn branch_remote_name<'a>( &self, short_branch_name: impl Into<&'a BStr> ) -> Option<Name<'_>>
Returns the unvalidated name of the remote associated with the given short_branch_name
,
typically main
instead of refs/heads/main
.
In some cases, the returned name will be an URL.
Returns None
if the remote was not found or if the name contained illformed UTF-8.
See also Reference::remote_name()
for a more typesafe version
to be used when a Reference
is available.
source§impl Repository
impl Repository
General Configuration
sourcepub fn config_snapshot(&self) -> Snapshot<'_>
pub fn config_snapshot(&self) -> Snapshot<'_>
Return a snapshot of the configuration as seen upon opening the repository.
sourcepub fn config_snapshot_mut(&mut self) -> SnapshotMut<'_>
pub fn config_snapshot_mut(&mut self) -> SnapshotMut<'_>
Return a mutable snapshot of the configuration as seen upon opening the repository, starting a transaction. When the returned instance is dropped, it is applied in full, even if the reason for the drop is an error.
Note that changes to the configuration are in-memory only and are observed only the this instance
of the Repository
.
sourcepub fn filesystem_options(&self) -> Result<Capabilities, Error>
pub fn filesystem_options(&self) -> Result<Capabilities, Error>
Return filesystem options as retrieved from the repository configuration.
Note that these values have not been probed.
sourcepub fn stat_options(&self) -> Result<Options, Error>
Available on crate feature index
only.
pub fn stat_options(&self) -> Result<Options, Error>
index
only.Return filesystem options on how to perform stat-checks, typically in relation to the index.
Note that these values have not been probed.
sourcepub fn open_options(&self) -> &Options
pub fn open_options(&self) -> &Options
The options used to open the repository.
sourcepub fn ssh_connect_options(&self) -> Result<Options, Error>
Available on crate feature blocking-network-client
only.
pub fn ssh_connect_options(&self) -> Result<Options, Error>
blocking-network-client
only.Obtain options for use when connecting via ssh
.
sourcepub fn object_hash(&self) -> Kind
pub fn object_hash(&self) -> Kind
The kind of object hash the repository is configured to use.
source§impl Repository
impl Repository
sourcepub fn filter_pipeline(
&self,
tree_if_bare: Option<ObjectId>
) -> Result<(Pipeline<'_>, IndexPersistedOrInMemory), Error>
Available on crate feature attributes
only.
pub fn filter_pipeline( &self, tree_if_bare: Option<ObjectId> ) -> Result<(Pipeline<'_>, IndexPersistedOrInMemory), Error>
attributes
only.Configure a pipeline for converting byte buffers to the worktree representation, and byte streams to the git-internal
representation. Also return the index that was used when initializing the pipeline as it may be useful when calling
convert_to_git().
Bare repositories will either use HEAD^{tree}
for accessing all relevant worktree files or the given tree_if_bare
.
Note that this is considered a primitive as it operates on data directly and will not have permanent effects.
We also return the index that was used to configure the attributes cache (for accessing .gitattributes
), which can be reused
after it was possibly created from a tree, an expensive operation.
Performance
Note that when in a repository with worktree, files in the worktree will be read with priority, which causes at least a stat each time the directory is changed. This can be expensive if access isn’t in sorted order, which would cause more then necessary stats: one per directory.
source§impl Repository
impl Repository
sourcepub fn revision_graph<T>(&self) -> Graph<'_, T>
pub fn revision_graph<T>(&self) -> Graph<'_, T>
Create a graph data-structure capable of accelerating graph traversals and storing state of type T
with each commit
it encountered.
Note that the commitgraph will be used if it is present and readable, but it won’t be an error if it is corrupted. In that case, it will just not be used.
Note that a commitgraph is only allowed to be used if core.commitGraph
is true (the default), and that configuration errors are
ignored as well.
Performance
Note that the Graph can be sensitive to various object database settings that may affect the performance of the commit walk.
sourcepub fn commit_graph(&self) -> Result<Graph, Error>
pub fn commit_graph(&self) -> Result<Graph, Error>
Return a cache for commits and their graph structure, as managed by git commit-graph
, for accelerating commit walks on
a low level.
Note that revision_graph()
should be preferred for general purpose walks that don’t
rely on the actual commit cache to be present, while leveraging it if possible.
source§impl Repository
impl Repository
Identity handling.
Deviation
There is no notion of a default user like in git, and instead failing to provide a user
is fatal. That way, we enforce correctness and force application developers to take care
of this issue which can be done in various ways, for instance by setting
gitoxide.committer.nameFallback
and similar.
sourcepub fn committer(&self) -> Option<Result<SignatureRef<'_>, Error>>
pub fn committer(&self) -> Option<Result<SignatureRef<'_>, Error>>
Return the committer as configured by this repository, which is determined by…
- …the git configuration
committer.name|email
… - …the
GIT_COMMITTER_(NAME|EMAIL|DATE)
environment variables… - …the configuration for
user.name|email
as fallback…
…and in that order, or None
if no committer name or email was configured, or Some(Err(…))
if the committer date could not be parsed.
Note
The values are cached when the repository is instantiated.
Return the author as configured by this repository, which is determined by…
- …the git configuration
author.name|email
… - …the
GIT_AUTHOR_(NAME|EMAIL|DATE)
environment variables… - …the configuration for
user.name|email
as fallback…
…and in that order, or None
if there was nothing configured.
Note
The values are cached when the repository is instantiated.
source§impl Repository
impl Repository
Index access
sourcepub fn open_index(&self) -> Result<File, Error>
Available on crate feature index
only.
pub fn open_index(&self) -> Result<File, Error>
index
only.Open a new copy of the index file and decode it entirely.
It will use the index.threads
configuration key to learn how many threads to use.
Note that it may fail if there is no index.
sourcepub fn index(&self) -> Result<Index, Error>
Available on crate feature index
only.
pub fn index(&self) -> Result<Index, Error>
index
only.Return a shared worktree index which is updated automatically if the in-memory snapshot has become stale as the underlying file on disk has changed.
The index file is shared across all clones of this repository.
sourcepub fn try_index(&self) -> Result<Option<Index>, Error>
Available on crate feature index
only.
pub fn try_index(&self) -> Result<Option<Index>, Error>
index
only.Return a shared worktree index which is updated automatically if the in-memory snapshot has become stale as the underlying file
on disk has changed, or None
if no such file exists.
The index file is shared across all clones of this repository.
sourcepub fn index_or_load_from_head(&self) -> Result<IndexPersistedOrInMemory, Error>
Available on crate feature index
only.
pub fn index_or_load_from_head(&self) -> Result<IndexPersistedOrInMemory, Error>
index
only.Open the persisted worktree index or generate it from the current HEAD^{tree}
to live in-memory only.
Use this method to get an index in any repository, even bare ones that don’t have one naturally.
Note
The locally stored index is not guaranteed to represent HEAD^{tree}
if this repository is bare - bare repos
don’t naturally have an index and if an index is present it must have been generated by hand.
sourcepub fn index_from_tree(&self, tree: &oid) -> Result<File, Error>
Available on crate feature index
only.
pub fn index_from_tree(&self, tree: &oid) -> Result<File, Error>
index
only.Create new index-file, which would live at the correct location, in memory from the given tree
.
Note that this is an expensive operation as it requires recursively traversing the entire tree to unpack it into the index.
source§impl Repository
impl Repository
sourcepub fn into_sync(self) -> ThreadSafeRepository
pub fn into_sync(self) -> ThreadSafeRepository
Convert this instance into a ThreadSafeRepository
by dropping all thread-local data.
source§impl Repository
impl Repository
sourcepub fn git_dir(&self) -> &Path
pub fn git_dir(&self) -> &Path
Return the path to the repository itself, containing objects, references, configuration, and more.
Synonymous to path()
.
sourcepub fn git_dir_trust(&self) -> Trust
pub fn git_dir_trust(&self) -> Trust
The trust we place in the git-dir, with lower amounts of trust causing access to configuration to be limited.
sourcepub fn common_dir(&self) -> &Path
pub fn common_dir(&self) -> &Path
Returns the main git repository if this is a repository on a linked work-tree, or the git_dir
itself.
sourcepub fn index_path(&self) -> PathBuf
pub fn index_path(&self) -> PathBuf
Return the path to the worktree index file, which may or may not exist.
sourcepub fn modules_path(&self) -> Option<PathBuf>
Available on crate feature attributes
only.
pub fn modules_path(&self) -> Option<PathBuf>
attributes
only.The path to the .gitmodules
file in the worktree, if a worktree is available.
sourcepub fn path(&self) -> &Path
pub fn path(&self) -> &Path
The path to the .git
directory itself, or equivalent if this is a bare repository.
sourcepub fn work_dir(&self) -> Option<&Path>
pub fn work_dir(&self) -> Option<&Path>
Return the work tree containing all checked out files, if there is one.
sourcepub fn install_dir(&self) -> Result<PathBuf>
pub fn install_dir(&self) -> Result<PathBuf>
The directory of the binary path of the current process.
sourcepub fn prefix(&self) -> Result<Option<&Path>, Error>
pub fn prefix(&self) -> Result<Option<&Path>, Error>
Returns the relative path which is the components between the working tree and the current working dir (CWD).
Note that it may be None
if there is no work tree, or if CWD isn’t inside of the working tree directory.
Note that the CWD is obtained once upon instantiation of the repository.
source§impl Repository
impl Repository
sourcepub fn open_mailmap(&self) -> Snapshot
Available on crate feature mailmap
only.
pub fn open_mailmap(&self) -> Snapshot
mailmap
only.Similar to open_mailmap_into()
, but ignores all errors and returns at worst
an empty mailmap, e.g. if there is no mailmap or if there were errors loading them.
This represents typical usage within git, which also works with what’s there without considering a populated mailmap a reason to abort an operation, considering it optional.
sourcepub fn open_mailmap_into(&self, target: &mut Snapshot) -> Result<(), Error>
Available on crate feature mailmap
only.
pub fn open_mailmap_into(&self, target: &mut Snapshot) -> Result<(), Error>
mailmap
only.Try to merge mailmaps from the following locations into target
:
- read the
.mailmap
file without following symlinks from the working tree, if present - OR read
HEAD:.mailmap
if this repository is bare (i.e. has no working tree), if themailmap.blob
is not set. - read the mailmap as configured in
mailmap.blob
, if set. - read the file as configured by
mailmap.file
, following symlinks, if set.
Only the first error will be reported, and as many source mailmaps will be merged into target
as possible.
Parsing errors will be ignored.
source§impl Repository
impl Repository
Methods related to object creation.
sourcepub fn find_object(&self, id: impl Into<ObjectId>) -> Result<Object<'_>, Error>
pub fn find_object(&self, id: impl Into<ObjectId>) -> Result<Object<'_>, Error>
Find the object with id
in the object database or return an error if it could not be found.
There are various legitimate reasons for an object to not be present, which is why
try_find_object(…)
might be preferable instead.
Performance Note
In order to get the kind of the object, is must be fully decoded from storage if it is packed with deltas. Loose object could be partially decoded, even though that’s not implemented.
sourcepub fn find_header(&self, id: impl Into<ObjectId>) -> Result<Header, Error>
pub fn find_header(&self, id: impl Into<ObjectId>) -> Result<Header, Error>
Obtain information about an object without fully decoding it, or fail if the object doesn’t exist.
Note that despite being cheaper than Self::find_object()
, there is still some effort traversing delta-chains.
sourcepub fn try_find_header(
&self,
id: impl Into<ObjectId>
) -> Result<Option<Header>, Error>
pub fn try_find_header( &self, id: impl Into<ObjectId> ) -> Result<Option<Header>, Error>
Obtain information about an object without fully decoding it, or None
if the object doesn’t exist.
Note that despite being cheaper than Self::try_find_object()
, there is still some effort traversing delta-chains.
sourcepub fn try_find_object(
&self,
id: impl Into<ObjectId>
) -> Result<Option<Object<'_>>, Error>
pub fn try_find_object( &self, id: impl Into<ObjectId> ) -> Result<Option<Object<'_>>, Error>
Try to find the object with id
or return None
if it wasn’t found.
sourcepub fn write_object(&self, object: impl WriteTo) -> Result<Id<'_>, Error>
pub fn write_object(&self, object: impl WriteTo) -> Result<Id<'_>, Error>
Write the given object into the object database and return its object id.
Note that we hash the object in memory to avoid storing objects that are already present. That way, we avoid writing duplicate objects using slow disks that will eventually have to be garbage collected.
sourcepub fn write_blob(&self, bytes: impl AsRef<[u8]>) -> Result<Id<'_>, Error>
pub fn write_blob(&self, bytes: impl AsRef<[u8]>) -> Result<Id<'_>, Error>
Write a blob from the given bytes
.
We avoid writing duplicate objects to slow disks that will eventually have to be garbage collected by pre-hashing the data, and checking if the object is already present.
sourcepub fn write_blob_stream(
&self,
bytes: impl Read + Seek
) -> Result<Id<'_>, Error>
pub fn write_blob_stream( &self, bytes: impl Read + Seek ) -> Result<Id<'_>, Error>
Write a blob from the given Read
implementation.
Note that we hash the object in memory to avoid storing objects that are already present. That way, we avoid writing duplicate objects using slow disks that will eventually have to be garbage collected.
If that is prohibitive, use the object database directly.
sourcepub fn tag(
&self,
name: impl AsRef<str>,
target: impl AsRef<oid>,
target_kind: Kind,
tagger: Option<SignatureRef<'_>>,
message: impl AsRef<str>,
constraint: PreviousValue
) -> Result<Reference<'_>, Error>
pub fn tag( &self, name: impl AsRef<str>, target: impl AsRef<oid>, target_kind: Kind, tagger: Option<SignatureRef<'_>>, message: impl AsRef<str>, constraint: PreviousValue ) -> Result<Reference<'_>, Error>
Create a tag reference named name
(without refs/tags/
prefix) pointing to a newly created tag object
which in turn points to target
and return the newly created reference.
It will be created with constraint
which is most commonly to only create it
or to force overwriting a possibly existing tag.
sourcepub fn commit_as<'a, 'c, Name, E>(
&self,
committer: impl Into<SignatureRef<'c>>,
author: impl Into<SignatureRef<'a>>,
reference: Name,
message: impl AsRef<str>,
tree: impl Into<ObjectId>,
parents: impl IntoIterator<Item = impl Into<ObjectId>>
) -> Result<Id<'_>, Error>where
Name: TryInto<FullName, Error = E>,
Error: From<E>,
pub fn commit_as<'a, 'c, Name, E>( &self, committer: impl Into<SignatureRef<'c>>, author: impl Into<SignatureRef<'a>>, reference: Name, message: impl AsRef<str>, tree: impl Into<ObjectId>, parents: impl IntoIterator<Item = impl Into<ObjectId>> ) -> Result<Id<'_>, Error>where Name: TryInto<FullName, Error = E>, Error: From<E>,
Similar to commit(…)
, but allows to create the commit with committer
and author
specified.
This forces setting the commit time and author time by hand. Note that typically, committer and author are the same.
sourcepub fn commit<Name, E>(
&self,
reference: Name,
message: impl AsRef<str>,
tree: impl Into<ObjectId>,
parents: impl IntoIterator<Item = impl Into<ObjectId>>
) -> Result<Id<'_>, Error>where
Name: TryInto<FullName, Error = E>,
Error: From<E>,
pub fn commit<Name, E>( &self, reference: Name, message: impl AsRef<str>, tree: impl Into<ObjectId>, parents: impl IntoIterator<Item = impl Into<ObjectId>> ) -> Result<Id<'_>, Error>where Name: TryInto<FullName, Error = E>, Error: From<E>,
Create a new commit object with message
referring to tree
with parents
, and point reference
to it. The commit is written without message encoding field, which can be assumed to be UTF-8.
author
and committer
fields are pre-set from the configuration, which can be altered
temporarily before the call if required.
reference
will be created if it doesn’t exist, and can be "HEAD"
to automatically write-through to the symbolic reference
that HEAD
points to if it is not detached. For this reason, detached head states cannot be created unless the HEAD
is detached
already. The reflog will be written as canonical git would do, like <operation> (<detail>): <summary>
.
The first parent id in parents
is expected to be the current target of reference
and the operation will fail if it is not.
If there is no parent, the reference
is expected to not exist yet.
The method fails immediately if a reference
lock can’t be acquired.
sourcepub fn empty_tree(&self) -> Tree<'_>
pub fn empty_tree(&self) -> Tree<'_>
Return an empty tree object, suitable for getting changes.
Note that it is special and doesn’t physically exist in the object database even though it can be returned. This means that this object can be used in an uninitialized, empty repository which would report to have no objects at all.
source§impl Repository
impl Repository
sourcepub fn pathspec(
&self,
patterns: impl IntoIterator<Item = impl AsRef<BStr>>,
inherit_ignore_case: bool,
index: &State,
attributes_source: Source
) -> Result<Pathspec<'_>, Error>
Available on crate feature attributes
only.
pub fn pathspec( &self, patterns: impl IntoIterator<Item = impl AsRef<BStr>>, inherit_ignore_case: bool, index: &State, attributes_source: Source ) -> Result<Pathspec<'_>, Error>
attributes
only.Create a new pathspec abstraction that allows to conduct searches using patterns
.
inherit_ignore_case
should be true
if patterns
will match against files on disk, or false
otherwise, for more natural matching
(but also note that git
does not do that).
index
may be needed to load attributes which is required only if patterns
refer to attributes via :(attr:…)
syntax.
In the same vein, attributes_source
affects where .gitattributes
files are read from if pathspecs need to match against attributes.
It will be initialized exactly how it would, and attribute matching will be conducted by reading the worktree first if available.
If that is not desirable, consider calling Pathspec::new()
directly.
sourcepub fn pathspec_defaults(&self) -> Result<Defaults, Error>
Available on crate feature attributes
only.
pub fn pathspec_defaults(&self) -> Result<Defaults, Error>
attributes
only.Return default settings that are required when parsing pathspecs by hand.
These are stemming from environment variables which have been converted to config settings, which now serve as authority for configuration.
sourcepub fn pathspec_defaults_inherit_ignore_case(
&self,
inherit_ignore_case: bool
) -> Result<Defaults, Error>
Available on crate feature attributes
only.
pub fn pathspec_defaults_inherit_ignore_case( &self, inherit_ignore_case: bool ) -> Result<Defaults, Error>
attributes
only.Similar to Self::pathspec_defaults(), but will automatically configure the returned defaults to match case-insensitively if the underlying
filesystem is also configured to be case-insensitive according to core.ignoreCase
, and inherit_ignore_case
is true
.
source§impl Repository
impl Repository
Obtain and alter references comfortably
sourcepub fn tag_reference(
&self,
name: impl AsRef<str>,
target: impl Into<ObjectId>,
constraint: PreviousValue
) -> Result<Reference<'_>, Error>
pub fn tag_reference( &self, name: impl AsRef<str>, target: impl Into<ObjectId>, constraint: PreviousValue ) -> Result<Reference<'_>, Error>
Create a lightweight tag with given name
(and without refs/tags/
prefix) pointing to the given target
, and return it as reference.
It will be created with constraint
which is most commonly to only create it
or to force overwriting a possibly existing tag.
sourcepub fn namespace(&self) -> Option<&Namespace>
pub fn namespace(&self) -> Option<&Namespace>
Returns the currently set namespace for references, or None
if it is not set.
Namespaces allow to partition references, and is configured per Easy
.
sourcepub fn clear_namespace(&mut self) -> Option<Namespace>
pub fn clear_namespace(&mut self) -> Option<Namespace>
Remove the currently set reference namespace and return it, affecting only this Easy
.
sourcepub fn set_namespace<'a, Name, E>(
&mut self,
namespace: Name
) -> Result<Option<Namespace>, Error>where
Name: TryInto<&'a PartialNameRef, Error = E>,
Error: From<E>,
pub fn set_namespace<'a, Name, E>( &mut self, namespace: Name ) -> Result<Option<Namespace>, Error>where Name: TryInto<&'a PartialNameRef, Error = E>, Error: From<E>,
Set the reference namespace to the given value, like "foo"
or "foo/bar"
.
Note that this value is shared across all Easy…
instances as the value is stored in the shared Repository
.
sourcepub fn reference<Name, E>(
&self,
name: Name,
target: impl Into<ObjectId>,
constraint: PreviousValue,
log_message: impl Into<BString>
) -> Result<Reference<'_>, Error>where
Name: TryInto<FullName, Error = E>,
Error: From<E>,
pub fn reference<Name, E>( &self, name: Name, target: impl Into<ObjectId>, constraint: PreviousValue, log_message: impl Into<BString> ) -> Result<Reference<'_>, Error>where Name: TryInto<FullName, Error = E>, Error: From<E>,
Create a new reference with name
, like refs/heads/branch
, pointing to target
, adhering to constraint
during creation and writing log_message
into the reflog. Note that a ref-log will be written even if log_message
is empty.
The newly created Reference is returned.
sourcepub fn edit_reference(&self, edit: RefEdit) -> Result<Vec<RefEdit>, Error>
pub fn edit_reference(&self, edit: RefEdit) -> Result<Vec<RefEdit>, Error>
Edit a single reference as described in edit
, and write reference logs as log_committer
.
One or more RefEdit
s are returned - symbolic reference splits can cause more edits to be performed. All edits have the previous
reference values set to the ones encountered at rest after acquiring the respective reference’s lock.
sourcepub fn edit_references(
&self,
edits: impl IntoIterator<Item = RefEdit>
) -> Result<Vec<RefEdit>, Error>
pub fn edit_references( &self, edits: impl IntoIterator<Item = RefEdit> ) -> Result<Vec<RefEdit>, Error>
Edit one or more references as described by their edits
.
Note that one can set the committer name for use in the ref-log by temporarily
overriding the git-config.
Returns all reference edits, which might be more than where provided due the splitting of symbolic references, and whose previous (old) values are the ones seen on in storage after the reference was locked.
sourcepub fn head(&self) -> Result<Head<'_>, Error>
pub fn head(&self) -> Result<Head<'_>, Error>
Return the repository head, an abstraction to help dealing with the HEAD
reference.
The HEAD
reference can be in various states, for more information, the documentation of Head
.
sourcepub fn head_id(&self) -> Result<Id<'_>, Error>
pub fn head_id(&self) -> Result<Id<'_>, Error>
Resolve the HEAD
reference, follow and peel its target and obtain its object id.
Note that this may fail for various reasons, most notably because the repository is freshly initialized and doesn’t have any commits yet.
Also note that the returned id is likely to point to a commit, but could also point to a tree or blob. It won’t, however, point to a tag as these are always peeled.
sourcepub fn head_name(&self) -> Result<Option<FullName>, Error>
pub fn head_name(&self) -> Result<Option<FullName>, Error>
Return the name to the symbolic reference HEAD
points to, or None
if the head is detached.
The difference to head_ref()
is that the latter requires the reference to exist,
whereas here we merely return a the name of the possibly unborn reference.
sourcepub fn head_ref(&self) -> Result<Option<Reference<'_>>, Error>
pub fn head_ref(&self) -> Result<Option<Reference<'_>>, Error>
Return the reference that HEAD
points to, or None
if the head is detached or unborn.
sourcepub fn head_commit(&self) -> Result<Commit<'_>, Error>
pub fn head_commit(&self) -> Result<Commit<'_>, Error>
Return the commit object the HEAD
reference currently points to after peeling it fully.
Note that this may fail for various reasons, most notably because the repository is freshly initialized and doesn’t have any commits yet. It could also fail if the head does not point to a commit.
sourcepub fn find_reference<'a, Name, E>(
&self,
name: Name
) -> Result<Reference<'_>, Error>where
Name: TryInto<&'a PartialNameRef, Error = E>,
Error: From<E>,
pub fn find_reference<'a, Name, E>( &self, name: Name ) -> Result<Reference<'_>, Error>where Name: TryInto<&'a PartialNameRef, Error = E>, Error: From<E>,
Find the reference with the given partial or full name
, like main
, HEAD
, heads/branch
or origin/other
,
or return an error if it wasn’t found.
Consider try_find_reference(…)
if the reference might not exist
without that being considered an error.
sourcepub fn references(&self) -> Result<Platform<'_>, Error>
pub fn references(&self) -> Result<Platform<'_>, Error>
sourcepub fn try_find_reference<'a, Name, E>(
&self,
name: Name
) -> Result<Option<Reference<'_>>, Error>where
Name: TryInto<&'a PartialNameRef, Error = E>,
Error: From<E>,
pub fn try_find_reference<'a, Name, E>( &self, name: Name ) -> Result<Option<Reference<'_>>, Error>where Name: TryInto<&'a PartialNameRef, Error = E>, Error: From<E>,
Try to find the reference named name
, like main
, heads/branch
, HEAD
or origin/other
, and return it.
Otherwise return None
if the reference wasn’t found.
If the reference is expected to exist, use find_reference()
.
source§impl Repository
impl Repository
sourcepub fn remote_at<Url, E>(&self, url: Url) -> Result<Remote<'_>, Error>where
Url: TryInto<Url, Error = E>,
Error: From<E>,
pub fn remote_at<Url, E>(&self, url: Url) -> Result<Remote<'_>, Error>where Url: TryInto<Url, Error = E>, Error: From<E>,
Create a new remote available at the given url
.
It’s configured to fetch included tags by default, similar to git.
See with_fetch_tags(…)
for a way to change it.
sourcepub fn remote_at_without_url_rewrite<Url, E>(
&self,
url: Url
) -> Result<Remote<'_>, Error>where
Url: TryInto<Url, Error = E>,
Error: From<E>,
pub fn remote_at_without_url_rewrite<Url, E>( &self, url: Url ) -> Result<Remote<'_>, Error>where Url: TryInto<Url, Error = E>, Error: From<E>,
Create a new remote available at the given url
similarly to remote_at()
,
but don’t rewrite the url according to rewrite rules.
This eliminates a failure mode in case the rewritten URL is faulty, allowing to selectively apply rewrite
rules later and do so non-destructively.
sourcepub fn find_remote<'a>(
&self,
name_or_url: impl Into<&'a BStr>
) -> Result<Remote<'_>, Error>
pub fn find_remote<'a>( &self, name_or_url: impl Into<&'a BStr> ) -> Result<Remote<'_>, Error>
Find the configured remote with the given name_or_url
or report an error,
similar to try_find_remote(…)
.
Note that we will obtain remotes only if we deem them trustworthy.
sourcepub fn find_default_remote(
&self,
direction: Direction
) -> Option<Result<Remote<'_>, Error>>
pub fn find_default_remote( &self, direction: Direction ) -> Option<Result<Remote<'_>, Error>>
Find the default remote as configured, or None
if no such configuration could be found.
See remote_default_name()
for more information on the direction
parameter.
sourcepub fn try_find_remote<'a>(
&self,
name_or_url: impl Into<&'a BStr>
) -> Option<Result<Remote<'_>, Error>>
pub fn try_find_remote<'a>( &self, name_or_url: impl Into<&'a BStr> ) -> Option<Result<Remote<'_>, Error>>
Find the configured remote with the given name_or_url
or return None
if it doesn’t exist,
for the purpose of fetching or pushing data.
There are various error kinds related to partial information or incorrectly formatted URLs or ref-specs.
Also note that the created Remote
may have neither fetch nor push ref-specs set at all.
Note that ref-specs are de-duplicated right away which may change their order. This doesn’t affect matching in any way as negations/excludes are applied after includes.
We will only include information if we deem it trustworthy.
sourcepub fn find_fetch_remote(
&self,
name_or_url: Option<&BStr>
) -> Result<Remote<'_>, Error>
pub fn find_fetch_remote( &self, name_or_url: Option<&BStr> ) -> Result<Remote<'_>, Error>
This method emulate what git fetch <remote>
does in order to obtain a remote to fetch from.
As such, with name_or_url
being Some
, it will:
- use
name_or_url
verbatim if it is a URL, creating a new remote in memory as needed. - find the named remote if
name_or_url
is a remote name
If name_or_url
is None
:
- use the current
HEAD
branch to find a configured remote - fall back to either a generally configured remote or the only configured remote.
Fail if no remote could be found despite all of the above.
sourcepub fn try_find_remote_without_url_rewrite<'a>(
&self,
name_or_url: impl Into<&'a BStr>
) -> Option<Result<Remote<'_>, Error>>
pub fn try_find_remote_without_url_rewrite<'a>( &self, name_or_url: impl Into<&'a BStr> ) -> Option<Result<Remote<'_>, Error>>
Similar to try_find_remote()
, but removes a failure mode if rewritten URLs turn out to be invalid
as it skips rewriting them.
Use this in conjunction with Remote::rewrite_urls()
to non-destructively apply the rules and keep the failed urls unchanged.
source§impl Repository
impl Repository
Methods for resolving revisions by spec or working with the commit graph.
sourcepub fn rev_parse<'a>(
&self,
spec: impl Into<&'a BStr>
) -> Result<Spec<'_>, Error>
Available on crate feature revision
only.
pub fn rev_parse<'a>( &self, spec: impl Into<&'a BStr> ) -> Result<Spec<'_>, Error>
revision
only.Parse a revision specification and turn it into the object(s) it describes, similar to git rev-parse
.
Deviation
@
actually stands forHEAD
, whereasgit
resolves it to the object pointed to byHEAD
without making theHEAD
ref available for lookups.
source§impl Repository
impl Repository
sourcepub fn is_shallow(&self) -> bool
pub fn is_shallow(&self) -> bool
Return true
if the repository is a shallow clone, i.e. contains history only up to a certain depth.
sourcepub fn shallow_commits(&self) -> Result<Option<Commits>, Error>
pub fn shallow_commits(&self) -> Result<Option<Commits>, Error>
Return a shared list of shallow commits which is updated automatically if the in-memory snapshot has become stale as the underlying file on disk has changed.
The list of shallow commits represents the shallow boundary, beyond which we are lacking all (parent) commits.
Note that the list is never empty, as Ok(None)
is returned in that case indicating the repository
isn’t a shallow clone.
The shared list is shared across all clones of this repository.
sourcepub fn shallow_file(&self) -> PathBuf
pub fn shallow_file(&self) -> PathBuf
Return the path to the shallow
file which contains hashes, one per line, that describe commits that don’t have their
parents within this repository.
Note that it may not exist if the repository isn’t actually shallow.
source§impl Repository
impl Repository
sourcepub fn state(&self) -> Option<InProgress>
pub fn state(&self) -> Option<InProgress>
Returns the status of an in progress operation on a repository or None
if no operation is currently in progress.
Note to be confused with the repositories ‘status’.
source§impl Repository
impl Repository
sourcepub fn open_modules_file(&self) -> Result<Option<File>, Error>
Available on crate feature attributes
only.
pub fn open_modules_file(&self) -> Result<Option<File>, Error>
attributes
only.Open the .gitmodules
file as present in the worktree, or return None
if no such file is available.
Note that git configuration is also contributing to the result based on the current snapshot.
Note that his method will not look in other places, like the index or the HEAD
tree.
sourcepub fn modules(&self) -> Result<Option<ModulesSnapshot>, Error>
Available on crate feature attributes
only.
pub fn modules(&self) -> Result<Option<ModulesSnapshot>, Error>
attributes
only.Return a shared .gitmodules
file which is updated automatically if the in-memory snapshot
has become stale as the underlying file on disk has changed. The snapshot based on the file on disk is shared across all
clones of this repository.
If a file on disk isn’t present, we will try to load it from the index, and finally from the current tree. In the latter two cases, the result will not be cached in this repository instance as we can’t detect freshness anymore, so time this method is called a new modules file will be created.
Note that git configuration is also contributing to the result based on the current snapshot.
source§impl Repository
impl Repository
Interact with individual worktrees and their information.
sourcepub fn worktrees(&self) -> Result<Vec<Proxy<'_>>>
pub fn worktrees(&self) -> Result<Vec<Proxy<'_>>>
Return a list of all linked worktrees sorted by private git dir path as a lightweight proxy.
Note that these need additional processing to become usable, but provide a first glimpse a typical worktree information.
sourcepub fn main_repo(&self) -> Result<Repository, Error>
pub fn main_repo(&self) -> Result<Repository, Error>
Return the repository owning the main worktree, typically from a linked worktree.
Note that it might be the one that is currently open if this repository doesn’t point to a linked worktree. Also note that the main repo might be bare.
sourcepub fn worktree(&self) -> Option<Worktree<'_>>
pub fn worktree(&self) -> Option<Worktree<'_>>
Return the currently set worktree if there is one, acting as platform providing a validated worktree base path.
Note that there would be None
if this repository is bare
and the parent Repository
was instantiated without
registered worktree in the current working dir, even if no .git
file or directory exists.
It’s merely based on configuration, see Worktree::dot_git_exists() for a way to perform more validation.
sourcepub fn is_bare(&self) -> bool
pub fn is_bare(&self) -> bool
Return true if this repository is bare, and has no main work tree.
This is not to be confused with the worktree()
worktree, which may exists if this instance
was opened in a worktree that was created separately.
sourcepub fn worktree_stream(
&self,
id: impl Into<ObjectId>
) -> Result<(Stream, File), Error>
Available on crate feature worktree-stream
only.
pub fn worktree_stream( &self, id: impl Into<ObjectId> ) -> Result<(Stream, File), Error>
worktree-stream
only.If id
points to a tree, produce a stream that yields one worktree entry after the other. The index of the tree at id
is returned as well as it is an intermediate byproduct that might be useful to callers.
The entries will look exactly like they would if one would check them out, with filters applied.
The export-ignore
attribute is used to skip blobs or directories to which it applies.
sourcepub fn worktree_archive(
&self,
stream: Stream,
out: impl Write + Seek,
blobs: impl Count,
should_interrupt: &AtomicBool,
options: Options
) -> Result<(), Error>
Available on crate feature worktree-archive
only.
pub fn worktree_archive( &self, stream: Stream, out: impl Write + Seek, blobs: impl Count, should_interrupt: &AtomicBool, options: Options ) -> Result<(), Error>
worktree-archive
only.Produce an archive from the stream
and write it to out
according to options
.
Use blob
to provide progress for each entry written to out
, and note that it should already be initialized to the amount
of expected entries, with should_interrupt
being queried between each entry to abort if needed, and on each write to out
.
Performance
Be sure that out
is able to handle a lot of write calls. Otherwise wrap it in a BufWriter
.
Additional progress and fine-grained interrupt handling
For additional progress reporting, wrap out
into a writer that counts throughput on each write.
This can also be used to react to interrupts on each write, instead of only for each entry.
Trait Implementations§
source§impl Clone for Repository
impl Clone for Repository
source§impl Debug for Repository
impl Debug for Repository
source§impl From<&ThreadSafeRepository> for Repository
impl From<&ThreadSafeRepository> for Repository
source§fn from(repo: &ThreadSafeRepository) -> Self
fn from(repo: &ThreadSafeRepository) -> Self
source§impl From<PrepareCheckout> for Repository
Available on crate feature worktree-mutation
only.
impl From<PrepareCheckout> for Repository
worktree-mutation
only.source§fn from(prep: PrepareCheckout) -> Self
fn from(prep: PrepareCheckout) -> Self
source§impl From<PrepareFetch> for Repository
impl From<PrepareFetch> for Repository
source§fn from(prep: PrepareFetch) -> Self
fn from(prep: PrepareFetch) -> Self
source§impl From<Repository> for ThreadSafeRepository
impl From<Repository> for ThreadSafeRepository
source§fn from(r: Repository) -> Self
fn from(r: Repository) -> Self
source§impl From<ThreadSafeRepository> for Repository
impl From<ThreadSafeRepository> for Repository
source§fn from(repo: ThreadSafeRepository) -> Self
fn from(repo: ThreadSafeRepository) -> Self
source§impl PartialEq<Repository> for Repository
impl PartialEq<Repository> for Repository
source§fn eq(&self, other: &Repository) -> bool
fn eq(&self, other: &Repository) -> bool
self
and other
values to be equal, and is used
by ==
.