Re: [PATCH 4/4] Clean up work-tree handling
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:43:25
Johannes Schindelin [off-list ref] writes:
The old version of work-tree support was an unholy mess, barely readable, and not to the point. For example, why do you have to provide a worktree, when it is not used? As in "git status". Now it works. ...
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).