From: "Nguyễn Thái Ngọc Duy" <pclouds@gmail.com>
To: git@vger.kernel.org
Subject: [PATCH 9/9] Documentation: update api-builtin and api-setup
Date: Wed, 27 Feb 2008 23:40:45 +0700 [thread overview]
Message-ID: <20080227164045.GA28142@laptop> (raw)
In-Reply-To: <cover.1204130175.git.pclouds@gmail.com>
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
---
Documentation/technical/api-builtin.txt | 10 ++++
Documentation/technical/api-setup.txt | 70 +++++++++++++++++++++++++++----
2 files changed, 72 insertions(+), 8 deletions(-)
diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt
index 52cdb4c..f0d988b 100644
--- a/Documentation/technical/api-builtin.txt
+++ b/Documentation/technical/api-builtin.txt
@@ -33,6 +33,10 @@ git:
If the standard output is connected to a tty, spawn a pager and
feed our output to it.
+`NEED_WORK_TREE`::
+
+ Make sure there is a work tree to work on.
+
. Add `builtin-foo.o` to `BUILTIN_OBJS` in `Makefile`.
Additionally, if `foo` is a new command, there are 3 more things to do:
@@ -59,5 +63,11 @@ to the subdirectory the command started from. This allows you to
convert a user-supplied pathname (typically relative to that directory)
to a pathname relative to the top of the work tree.
+`NEED_WORK_TREE` also set `prefix` like `RUN_SETUP`. But it will `die()`
+if there is no work tree.
+
+If neither `NEED_WORK_TREE` nor `RUN_SETUP` is set, `prefix` is always `NULL`.
+No chdir(2) will be done.
+
The return value from `cmd_foo()` becomes the exit status of the
command.
diff --git a/Documentation/technical/api-setup.txt b/Documentation/technical/api-setup.txt
index 4f63a04..43e5a81 100644
--- a/Documentation/technical/api-setup.txt
+++ b/Documentation/technical/api-setup.txt
@@ -1,13 +1,67 @@
setup API
=========
-Talk about
+End-user point-of-view how the setup works
+------------------------------------------
-* setup_git_directory()
-* setup_git_directory_gently()
-* is_inside_git_dir()
-* is_inside_work_tree()
-* setup_work_tree()
-* get_pathspec()
+. If you have `GIT_DIR` exported, then no discovery is attempted.
+ We use the `GIT_DIR` you set it, and the repository lives
+ there. `$GIT_DIR/config` is the repository config.
-(Dscho)
+. Otherwise we do the usual discovery going up to find the
+ repository.
+
+. If you have `GIT_WORK_TREE` exported, or otherwise if the
+ config has `core.worktree`, that's where your worktree is.
+ If these variables point to an invalid place, you have no worktree.
+
+. Otherwise, if you have `GIT_DIR` exported, you do not have a
+ worktree. Else one level above your `$GIT_DIR` is the toplevel
+ of your worktree.
+
+Repository setup
+----------------
+
+At startup:
+
+. If the command always need a repository, call
+ `setup_git_directory()`. It will ensure you have a valid
+ repository. It will `die()` otherwise. If a worktree is detected,
+ it will be setup automatically.
+
+. If the command can optionally run in a repository, use
+ `setup_git_directory_gently(&nongit_ok)`,which is similar
+ to `setup_git_directory()` except it won't `die()`
+ but sets `nongit_ok` to true if run outside a repository.
+ No chdir(2) is done.
+
+. If you don't want worktree setup at all, but always need a git repository,
+ you can use `setup_git_directory_gently(NULL)`.
+
+Do not access git repository (even indirectly like `git_config()`) before
+calling one of these functions. Otherwise you may encounter `die()` if git
+fails to automatically find/setup a repository.
+
+Working directory setup
+-----------------------
+
+If `setup_git_directory()` is used, worktree can be optionally setup already.
+To check if work tree has been setup, use `get_git_work_tree()`. The return
+value is `NULL` if no work tree is setup or work tree directory otherwise.
+
+If you need a working directory, use `setup_work_tree()`. It will
+move current directory to top-level working directory and return
+a prefix. It will `die()` if unable to setup working directory.
+
+Miscellanous functions
+----------------------
+
+To know where `$GIT_DIR` is, use `get_git_dir()`. It will always return
+an absolute path. To know where `$GIT_WORK_TREE` is, use
+`get_git_work_tree()`. To check if you are inside a worktree or a git
+repository, use `is_inside_work_tree()` or `is_inside_git_dir()` respectively.
+There functions may be not valid until `setup_git_directory*()` is called.
+
+When working with pathspecs and prefix, you can use `get_pathspec()`
+to auto prepend a given prefix to pathspecs. Other helpful functions
+are `prefix_path()`, `prefix_filename()`
--
1.5.4.2.281.g28d0e
next prev parent reply other threads:[~2008-02-27 16:41 UTC|newest]
Thread overview: 24+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <cover.1204130175.git.pclouds@gmail.com>
2008-02-27 16:38 ` [PATCH 1/9] "git read-tree -m" and the like require worktree Nguyễn Thái Ngọc Duy
2008-02-28 0:48 ` Junio C Hamano
2008-02-28 3:22 ` Nguyen Thai Ngoc Duy
2008-02-27 16:38 ` [PATCH 2/9] Make sure setup_git_directory is called before accessing repository Nguyễn Thái Ngọc Duy
2008-02-27 16:38 ` [PATCH 3/9] Make get_git_dir() and 'git rev-parse --git-dir' absolute path Nguyễn Thái Ngọc Duy
2008-02-27 16:39 ` [PATCH 4/9] Make setup_work_tree() return new prefix Nguyễn Thái Ngọc Duy
2008-02-28 11:30 ` Johannes Schindelin
2008-02-28 13:02 ` Nguyen Thai Ngoc Duy
2008-02-28 15:53 ` Johannes Schindelin
2008-02-27 16:39 ` [PATCH 5/9] http-push: Avoid calling setup_git_directory() twice Nguyễn Thái Ngọc Duy
2008-02-28 0:50 ` Junio C Hamano
2008-02-28 3:26 ` Nguyen Thai Ngoc Duy
2008-02-27 16:39 ` [PATCH 6/9] Completely move out worktree setup from setup_git_directory_gently() Nguyễn Thái Ngọc Duy
2008-02-28 2:17 ` Junio C Hamano
2008-02-28 3:31 ` Nguyen Thai Ngoc Duy
2008-02-28 3:37 ` Junio C Hamano
2008-02-28 4:09 ` Nguyen Thai Ngoc Duy
2008-02-28 11:26 ` Johannes Schindelin
2008-02-28 12:52 ` Nguyen Thai Ngoc Duy
2008-02-27 16:40 ` [PATCH 7/9] builtin-archive: mark unused prefix "unused_prefix" Nguyễn Thái Ngọc Duy
2008-02-27 16:40 ` [PATCH 8/9] Make setup_git_directory() auto-setup worktree if found Nguyễn Thái Ngọc Duy
2008-02-27 16:40 ` Nguyễn Thái Ngọc Duy [this message]
2011-04-05 8:07 ` [PATCH 9/9] Documentation: update api-builtin and api-setup Jonathan Nieder
2011-04-05 11:32 ` Nguyen Thai Ngoc Duy
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20080227164045.GA28142@laptop \
--to=pclouds@gmail.com \
--cc=git@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).