Documentation/technical/api-setup.txt

   1 setup API
   2 =========
   3
   4 Talk about
   5
   6 * setup_git_directory()
   7 * setup_git_directory_gently()
   8 * is_inside_git_dir()
   9 * is_inside_work_tree()
  10 * setup_work_tree()
  11
  12 (Dscho)
  13
  14 Pathspec
  15 --------
  16
  17 See glossary-context.txt for the syntax of pathspec. In memory, a
  18 pathspec set is represented by "struct pathspec" and is prepared by
  19 parse_pathspec(). This function takes several arguments:
  20
  21 - magic_mask specifies what features that are NOT supported by the
  22   following code. If a user attempts to use such a feature,
  23   parse_pathspec() can reject it early.
  24
  25 - flags specifies other things that the caller wants parse_pathspec to
  26   perform.
  27
  28 - prefix and args come from cmd_* functions
  29
  30 get_pathspec() is obsolete and should never be used in new code.
  31
  32 parse_pathspec() helps catch unsupported features and reject them
  33 politely. At a lower level, different pathspec-related functions may
  34 not support the same set of features. Such pathspec-sensitive
  35 functions are guarded with GUARD_PATHSPEC(), which will die in an
  36 unfriendly way when an unsupported feature is requested.
  37
  38 The command designers are supposed to make sure that GUARD_PATHSPEC()
  39 never dies. They have to make sure all unsupported features are caught
  40 by parse_pathspec(), not by GUARD_PATHSPEC. grepping GUARD_PATHSPEC()
  41 should give the designers all pathspec-sensitive codepaths and what
  42 features they support.
  43
  44 A similar process is applied when a new pathspec magic is added. The
  45 designer lifts the GUARD_PATHSPEC restriction in the functions that
  46 support the new magic. At the same time (s)he has to make sure this
  47 new feature will be caught at parse_pathspec() in commands that cannot
  48 handle the new magic in some cases. grepping parse_pathspec() should
  49 help.