Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@xxxxxxxxx> --- Documentation/technical/api-builtin.txt | 10 ++++ Documentation/technical/api-setup.txt | 91 ++++++++++++++++++++++++++++--- 2 files changed, 93 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..6f2defa 100644 --- a/Documentation/technical/api-setup.txt +++ b/Documentation/technical/api-setup.txt @@ -1,13 +1,88 @@ 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. Note that `setup_git_directory()` + can only be called once. + +. 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()` + +Shell-based setup +----------------- + +At startup, you need to `source git-sh-setup`. If your command does not always +require a repository, set variable `NONGIT_OK` before sourcing git-sh-setup. + +If the command requires worktree, call `require_work_tree` (after +git-sh-setup). + +Two variables `USAGE` and `LONG_USAGE` can be optionally set before sourcing +git-sh-setup. They will be printed as help usage. + +To check if a repository is a bare repository, `is_bare_repository` can be +used. + +There are several `git rev-parse` options to help shell scripts initialize +their environment. Those are `--show-prefix`, `--show-cdup`, `--git-dir`, +`--is-inside-git-dir`, `--is-inside-work-tree`, `--is-bare-repository` and +`--parseopt`. Please refer to `git rev-parse` man page for more information. -- 1.5.4.2.281.g28d0e -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
