setup API ========= Talk about * setup_git_directory() * setup_git_directory_gently() * is_inside_git_dir() * is_inside_work_tree() * setup_work_tree() (Dscho) Pathspec -------- See glossary-context.txt for the syntax of pathspec. In memory, a pathspec set is represented by "struct pathspec" and is prepared by parse_pathspec(). This function takes several arguments: - magic_mask specifies what features that are NOT supported by the following code. If a user attempts to use such a feature, parse_pathspec() can reject it early. - flags specifies other things that the caller wants parse_pathspec to perform. - prefix and args come from cmd_* functions get_pathspec() is obsolete and should never be used in new code. parse_pathspec() helps catch unsupported features and reject them politely. At a lower level, different pathspec-related functions may not support the same set of features. Such pathspec-sensitive functions are guarded with GUARD_PATHSPEC(), which will die in an unfriendly way when an unsupported feature is requested. The command designers are supposed to make sure that GUARD_PATHSPEC() never dies. They have to make sure all unsupported features are caught by parse_pathspec(), not by GUARD_PATHSPEC. grepping GUARD_PATHSPEC() should give the designers all pathspec-sensitive codepaths and what features they support. A similar process is applied when a new pathspec magic is added. The designer lifts the GUARD_PATHSPEC restriction in the functions that support the new magic. At the same time (s)he has to make sure this new feature will be caught at parse_pathspec() in commands that cannot handle the new magic in some cases. grepping parse_pathspec() should help.