gix_discover/
lib.rs

1//! Find git repositories or search them upwards from a starting point, or determine if a directory looks like a git repository.
2//!
3//! Note that detection methods are educated guesses using the presence of files, without looking too much into the details.
4//!
5//! ## Examples
6//!
7//! ```
8//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
9//! # let dir = tempfile::tempdir()?;
10//! # let git_dir = dir.path().join(".git");
11//! # std::fs::create_dir_all(git_dir.join("objects"))?;
12//! # std::fs::create_dir_all(git_dir.join("refs").join("heads"))?;
13//! # std::fs::write(git_dir.join("HEAD"), b"ref: refs/heads/main\n")?;
14//! # std::fs::write(
15//! #     git_dir.join("refs").join("heads").join("main"),
16//! #     b"1111111111111111111111111111111111111111\n",
17//! # )?;
18//! # let nested = dir.path().join("src").join("module");
19//! # std::fs::create_dir_all(&nested)?;
20//! let (path, _trust) = gix_discover::upwards(&nested)?;
21//! let (repository_dir, worktree_dir) = path.into_repository_and_work_tree_directories();
22//!
23//! assert_eq!(repository_dir, git_dir);
24//! assert_eq!(worktree_dir, Some(dir.path().to_path_buf()));
25//! assert!(gix_discover::is_git(&repository_dir).is_ok());
26//! # Ok(()) }
27//! ```
28#![deny(missing_docs)]
29#![forbid(unsafe_code)]
30
31/// The name of the `.git` directory.
32pub const DOT_GIT_DIR: &str = ".git";
33
34/// The name of the `modules` sub-directory within a `.git` directory for keeping submodule checkouts.
35pub const MODULES: &str = "modules";
36
37///
38pub mod repository;
39
40///
41pub mod is_git {
42    use std::path::PathBuf;
43
44    /// The error returned by [`crate::is_git()`].
45    #[derive(Debug, thiserror::Error)]
46    #[expect(missing_docs)]
47    pub enum Error {
48        #[error("Could not find a valid HEAD reference")]
49        FindHeadRef(#[from] gix_ref::file::find::existing::Error),
50        #[error("Missing HEAD at '.git/HEAD'")]
51        MissingHead,
52        #[error("Expected HEAD at '.git/HEAD', got '.git/{}'", .name)]
53        MisplacedHead { name: bstr::BString },
54        #[error("Expected an objects directory at '{}'", .missing.display())]
55        MissingObjectsDirectory { missing: PathBuf },
56        #[error("The worktree's private repo's commondir file at '{}' or it could not be read", .missing.display())]
57        MissingCommonDir { missing: PathBuf, source: std::io::Error },
58        #[error("Expected a refs directory at '{}'", .missing.display())]
59        MissingRefsDirectory { missing: PathBuf },
60        #[error(transparent)]
61        GitFile(#[from] crate::path::from_gitdir_file::Error),
62        #[error("Could not retrieve metadata of \"{path}\"")]
63        Metadata { source: std::io::Error, path: PathBuf },
64        #[error(
65            "The repository's config file doesn't exist or didn't have a 'bare' configuration or contained core.worktree without value"
66        )]
67        Inconclusive,
68        #[error("Could not obtain current directory for resolving the '.' repository path")]
69        CurrentDir(#[from] std::io::Error),
70    }
71}
72
73mod is;
74#[expect(
75    deprecated,
76    reason = "this re-export preserves compatibility with the deprecated API"
77)]
78pub use is::submodule_git_dir as is_submodule_git_dir;
79pub use is::{bare as is_bare, git as is_git};
80
81///
82pub mod upwards;
83pub use upwards::function::{discover as upwards, discover_opts as upwards_opts};
84
85///
86pub mod path;
87
88///
89pub mod parse;
gix_discover/lib.rs

gix_discover/
lib.rs
