Add repo open and discover examples

arrbee · arrbee · commit 39ae3d4e85af · 2014-03-05T10:23:34.000-08:00
diff --git a/docs/guides/101-samples/index.md b/docs/guides/101-samples/index.md
@@ -52,10 +52,15 @@ int error = git_repository_init(&repo, "/tmp/…", true);
 <h3 id="repositories_init_options">Init (Options)</h3>
 
 ```c
+int error;
+git_repository *repo = NULL;
 git_repository_init_options opts = GIT_REPOSITORY_INIT_OPTIONS_INIT;
+
 /* Customize options */
-git_repository *repo = NULL;
-int error = git_repository_init_ext(&repo, "/tmp/…", &opts);
+opts.flags |= GIT_REPOSITORY_INIT_MKPATH; /* mkdir as needed to create repo */
+opts.description = "My repository has a custom description";
+
+error = git_repository_init_ext(&repo, "/tmp/…", &opts);
 ```
 
 ([`git_repository_init_ext`](http://libgit2.github.com/libgit2/#HEAD/group/repository/git_repository_init_ext),
@@ -139,8 +144,8 @@ error = git_repository_init(&repo, "/tmp/…", true);
 
 /* Create an 'origin' remote with the mirror fetch refspec */
 git_remote *origin = NULL;
-error = git_remote_create_with_fetchspec(&origin, repo, "origin",
-                                         "http://…", "+refs/*:refs/*");
+error = git_remote_create_with_fetchspec(
+    &origin, repo, "origin", "http://…", "+refs/*:refs/*");
 
 /* Set remote.origin.mirror = true for compatibility with git-core */
 git_config *cfg = NULL;
@@ -168,14 +173,60 @@ int error = git_repository_open(&repo, "/tmp/…");
 <h3 id="repositories_opening_options">Opening (Options)</h3>
 
 ```c
+int error;
 git_repository *repo = NULL;
-int error = git_repository_open_ext(&repo, "/tmp/…",
-  GIT_REPOSITORY_OPEN_NO_SEARCH, NULL);
+
+/* Open repository, walking up from given directory to find root */
+error = git_repository_open_ext(&repo, "/tmp/…", 0, NULL);
+
+/* Open repository in given directory (or fail if not a repository) */
+error = git_repository_open_ext(
+    &repo, "/tmp/…", GIT_REPOSITORY_OPEN_NO_SEARCH, NULL);
+
+/* Open repository with "ceiling" directories list to limit walking up */
+error = git_repository_open_ext(
+    &repo, "/home/acct/…, GIT_REPOSITORY_OPEN_CROSS_FS, "/tmp:/usr:/home");
 ```
 
 ([`git_repository_open_ext`](http://libgit2.github.com/libgit2/#HEAD/group/repository/git_repository_open_ext),
 [`git_repository_open_flag_t`](http://libgit2.github.com/libgit2/#HEAD/type/git_repository_open_flag_t))
 
+<h3 id="repositories_open_bare">Opening (Bare)</h3>
+
+A fast way of opening a bare repository when the exact path is known.
+
+```c
+git_repository *repo = NULL;
+int error = git_repository_open_bare(&repo, "/var/data/…/repo.git");
+```
+
+([`git_repository_open_bare`](http://libgit2.github.com/libgit2/#HEAD/group/repository/git_repository_open_bare))
+
+<h3 id="repositories_openable">Is Directory A Repository?</h3>
+
+```c
+/* Pass NULL for the output parameter to not open the repo immediately */
+int error = git_repository_open_ext(
+    NULL, "/tmp/…", GIT_REPOSITORY_OPEN_NO_SEARCH, NULL);
+```
+
+([`git_repository_open_ext`](http://libgit2.github.com/libgit2/#HEAD/group/repository/git_repository_open_ext),
+[`git_repository_open_flag_t`](http://libgit2.github.com/libgit2/#HEAD/type/git_repository_open_flag_t))
+
+<h3 id="repositories_discover">Find Repository Root</h3>
+
+Check if a given path is inside a repository and return the repository
+root directory if found.
+
+```c
+git_buf root = {0};
+int error = git_repository_discover(&root, "/tmp/…", 0, NULL);
+…
+git_buf_free(&root); /* returned path data must be freed after use */
+```
+
+([`git_repository_discover`](http://libgit2.github.com/libgit2/#HEAD/group/repository/git_repository_discover))
+
 
 
 <h2 id="objects">Objects</h2>
