Add GIT_REPOSITORY_OPEN_FROM_ENV flag to respect $GIT_* environment vars

git_repository_open_ext provides parameters for the start path, whether
to search across filesystems, and what ceiling directories to stop at.
git commands have standard environment variables and defaults for each
of those, as well as various other parameters of the repository. To
avoid duplicate environment variable handling in users of libgit2, add a
GIT_REPOSITORY_OPEN_FROM_ENV flag, which makes git_repository_open_ext
automatically handle the appropriate environment variables. Commands
that intend to act just like those built into git itself can use this
flag to get the expected default behavior.

git_repository_open_ext with the GIT_REPOSITORY_OPEN_FROM_ENV flag
respects $GIT_DIR, $GIT_DISCOVERY_ACROSS_FILESYSTEM,
$GIT_CEILING_DIRECTORIES, $GIT_INDEX_FILE, $GIT_NAMESPACE,
$GIT_OBJECT_DIRECTORY, and $GIT_ALTERNATE_OBJECT_DIRECTORIES.  In the
future, when libgit2 gets worktree support, git_repository_open_env will
also respect $GIT_WORK_TREE and $GIT_COMMON_DIR; until then,
git_repository_open_ext with this flag will error out if either
$GIT_WORK_TREE or $GIT_COMMON_DIR is set.

1 files changed, 16 insertions, 1 deletions

diff --git a/include/git2/repository.h b/include/git2/repository.h
index f7efe0116..3d70d1b89 100644
--- a/include/git2/repository.h
+++ b/include/git2/repository.h
@@ -98,12 +98,26 @@ GIT_EXTERN(int) git_repository_discover(
  * * GIT_REPOSITORY_OPEN_NO_DOTGIT - Do not check for a repository by
  *   appending /.git to the start_path; only open the repository if
  *   start_path itself points to the git directory.
+ * * GIT_REPOSITORY_OPEN_FROM_ENV - Find and open a git repository,
+ *   respecting the environment variables used by the git command-line
+ *   tools. If set, `git_repository_open_ext` will ignore the other
+ *   flags and the `ceiling_dirs` argument, and will allow a NULL `path`
+ *   to use `GIT_DIR` or search from the current directory. The search
+ *   for a repository will respect $GIT_CEILING_DIRECTORIES and
+ *   $GIT_DISCOVERY_ACROSS_FILESYSTEM.  The opened repository will
+ *   respect $GIT_INDEX_FILE, $GIT_NAMESPACE, $GIT_OBJECT_DIRECTORY, and
+ *   $GIT_ALTERNATE_OBJECT_DIRECTORIES.  In the future, this flag will
+ *   also cause `git_repository_open_ext` to respect $GIT_WORK_TREE and
+ *   $GIT_COMMON_DIR; currently, `git_repository_open_ext` with this
+ *   flag will error out if either $GIT_WORK_TREE or $GIT_COMMON_DIR is
+ *   set.
  */
 typedef enum {
 	GIT_REPOSITORY_OPEN_NO_SEARCH = (1 << 0),
 	GIT_REPOSITORY_OPEN_CROSS_FS  = (1 << 1),
 	GIT_REPOSITORY_OPEN_BARE      = (1 << 2),
 	GIT_REPOSITORY_OPEN_NO_DOTGIT = (1 << 3),
+	GIT_REPOSITORY_OPEN_FROM_ENV  = (1 << 4),
 } git_repository_open_flag_t;
 
 /**
@@ -114,7 +128,8 @@ typedef enum {
  *        see if a repo at this path could be opened.
  * @param path Path to open as git repository.  If the flags
  *        permit "searching", then this can be a path to a subdirectory
- *        inside the working directory of the repository.
+ *        inside the working directory of the repository. May be NULL if
+ *        flags is GIT_REPOSITORY_OPEN_FROM_ENV.
  * @param flags A combination of the GIT_REPOSITORY_OPEN flags above.
  * @param ceiling_dirs A GIT_PATH_LIST_SEPARATOR delimited list of path
  *        prefixes at which the search for a containing repository should