Sixth batch
[git/git.git] / Documentation / technical / api-setup.txt
... / ...
CommitLineData
1setup API
2=========
3
4Talk 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
14Pathspec
15--------
16
17See glossary-context.txt for the syntax of pathspec. In memory, a
18pathspec set is represented by "struct pathspec" and is prepared by
19parse_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
30parse_pathspec() helps catch unsupported features and reject them
31politely. At a lower level, different pathspec-related functions may
32not support the same set of features. Such pathspec-sensitive
33functions are guarded with GUARD_PATHSPEC(), which will die in an
34unfriendly way when an unsupported feature is requested.
35
36The command designers are supposed to make sure that GUARD_PATHSPEC()
37never dies. They have to make sure all unsupported features are caught
38by parse_pathspec(), not by GUARD_PATHSPEC. grepping GUARD_PATHSPEC()
39should give the designers all pathspec-sensitive codepaths and what
40features they support.
41
42A similar process is applied when a new pathspec magic is added. The
43designer lifts the GUARD_PATHSPEC restriction in the functions that
44support the new magic. At the same time (s)he has to make sure this
45new feature will be caught at parse_pathspec() in commands that cannot
46handle the new magic in some cases. grepping parse_pathspec() should
47help.