From f675ea3cd73eab025a8392bb8ec6b3a5d7a1cc5f Mon Sep 17 00:00:00 2001
From: Edward Thomson <ethomson@edwardthomson.com>
Date: Wed, 11 Dec 2024 10:54:21 +0000
Subject: [PATCH] docs: remind people about `git_libgit2_init`

Currently `git_libgit2_init` must be called before you can work with the
library. Remind people about this as they read the documentation.
---
 include/git2/clone.h      |  4 ++++
 include/git2/repository.h | 24 ++++++++++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/include/git2/clone.h b/include/git2/clone.h
index 0d06a41df..b7a47ab48 100644
--- a/include/git2/clone.h
+++ b/include/git2/clone.h
@@ -200,6 +200,10 @@ GIT_EXTERN(int) git_clone_options_init(
  * git's defaults. You can use the options in the callback to
  * customize how these are created.
  *
+ * Note that the libgit2 library _must_ be initialized using
+ * `git_libgit2_init` before any APIs can be called, including
+ * this one.
+ *
  * @param[out] out pointer that will receive the resulting repository object
  * @param url the remote repository to clone
  * @param local_path local directory to clone to
diff --git a/include/git2/repository.h b/include/git2/repository.h
index a10ea3fcb..59c4d0f30 100644
--- a/include/git2/repository.h
+++ b/include/git2/repository.h
@@ -31,6 +31,10 @@ GIT_BEGIN_DECL
  * The method will automatically detect if 'path' is a normal
  * or bare repository or fail is 'path' is neither.
  *
+ * Note that the libgit2 library _must_ be initialized using
+ * `git_libgit2_init` before any APIs can be called, including
+ * this one.
+ *
  * @param[out] out pointer to the repo which will be opened
  * @param path the path to the repository
  * @return 0 or an error code
@@ -84,6 +88,10 @@ GIT_EXTERN(int) git_repository_wrap_odb(
  * The method will automatically detect if the repository is bare
  * (if there is a repository).
  *
+ * Note that the libgit2 library _must_ be initialized using
+ * `git_libgit2_init` before any APIs can be called, including
+ * this one.
+ *
  * @param out A pointer to a user-allocated git_buf which will contain
  * the found path.
  *
@@ -161,6 +169,10 @@ typedef enum {
 /**
  * Find and open a repository with extended controls.
  *
+ * Note that the libgit2 library _must_ be initialized using
+ * `git_libgit2_init` before any APIs can be called, including
+ * this one.
+ *
  * @param[out] out Pointer to the repo which will be opened.  This can
  *        actually be NULL if you only want to use the error code to
  *        see if a repo at this path could be opened.
@@ -189,6 +201,10 @@ GIT_EXTERN(int) git_repository_open_ext(
  * if you're e.g. hosting git repositories and need to access them
  * efficiently
  *
+ * Note that the libgit2 library _must_ be initialized using
+ * `git_libgit2_init` before any APIs can be called, including
+ * this one.
+ *
  * @param[out] out Pointer to the repo which will be opened.
  * @param bare_path Direct path to the bare repository
  * @return 0 on success, or an error code
@@ -214,6 +230,10 @@ GIT_EXTERN(void) git_repository_free(git_repository *repo);
  * TODO:
  *	- Reinit the repository
  *
+ * Note that the libgit2 library _must_ be initialized using
+ * `git_libgit2_init` before any APIs can be called, including
+ * this one.
+ *
  * @param[out] out pointer to the repo which will be created or reinitialized
  * @param path the path to the repository
  * @param is_bare if true, a Git repository without a working directory is
@@ -404,6 +424,10 @@ GIT_EXTERN(int) git_repository_init_options_init(
  * auto-detect the case sensitivity of the file system and if the
  * file system supports file mode bits correctly.
  *
+ * Note that the libgit2 library _must_ be initialized using
+ * `git_libgit2_init` before any APIs can be called, including
+ * this one.
+ *
  * @param out Pointer to the repo which will be created or reinitialized.
  * @param repo_path The path to the repository.
  * @param opts Pointer to git_repository_init_options struct.