Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
Without continuing with negatives, let's try to define the new,
corrected world order.
I do not think the following is exactly what your cleaned-up
version tries to perform, but I am writing this down primarily
to demonstrate the style and the level of detail I expect to
accompany a clean-up patch like this.
----------------------------------------------------------------
Definitions:
- You can have "checked out" files on the filesystem, and such
files are said to be in your "work tree". The directory
on the filesystem that corresponds to the toplevel entries of
the index and the tree objects directly contained in the
commit objects is called "the toplevel of the work tree",
or simply "work tree" if it is not ambiguous from the
context.
- The directory that holds git repository information is called
"git directory". This is typically .git directory at the
toplevel of your work tree, but not necessarily so.
- You can perform many git operations without a work tree, but
some operations fundamentally require you to have one
(e.g. checkout and diff, unless two tree-ishes are given, do
not make sense without a work tree).
There are four predicates, two interrogators, and two
manipulators:
- is_inside_git_dir(): this returns true if the $cwd is the git
directory or its subdirectory. [IS THIS STILL NEEDED???]
- is_inside_work_tree(): this returns true if the $cwd is
inside work tree (i.e. either at the toplevel of the work
tree or its subdirectory). [NEEDSHELP: is .git in the usual
layout considered "is_inside_work_tree()"? Should it?]
- is_bare_repository(): this returns true if no work tree is
found. There is a corresponding function usable from the
scripts.
- require_work_tree (shell): this is called by scripts that
needs to have a work tree to operate, and barfs otherwise.
- get_git_dir(): this returns the location of the git
directory. With GIT_DIR environment variable, or --git-dir
command line option, you can tell git to use a specific
directory as the git directory. Otherwise a directory that
looks like a git directory and whose name is .git is looked
for, in the $cwd or its parent directory. If there is no
such directory, and if the $cwd looks like a git directory,
$cwd is the git directory.
- get_git_work_tree(): this returns the location of the work
tree; it returns NULL if there is none. The command line
option --work-tree, or the environment variable GIT_WORK_TREE
can specify the location; otherwise, git directory is looked
for so that its configuration file can be read. If
core.worktree is there, that specifies the location.
Otherwise, if the basename of the git directory is .git, it
is the parent directory of the git directory. Otherwise, you
do not have work tree.
- set_git_dir(): used to set the git directory, internally to
handle --git-dir option;
- set_work_tree(): used to set the git directory, internally to
handle --work-tree option;
----------------------------------------------------------------
After writing the above down, it strikes me odd that we do not
have a predicate that says "we know the work tree is there".
If a command wants a work tree, and if you are outside the work
tree, then is_inside_work_tree() returns false and
get_git_work_tree() returns non NULL, so that is a good pair of
interface that can be mixed and matched (e.g. you can chdir to
the former to perform the whole tree operation, or refuse to
perform, based on is_inside_work_tree being false, cwd relative
operations).
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
