path: root/Documentation/technical/api-setup.txt
diff options
authorNguyễn Thái Ngọc Duy <>2013-07-14 08:35:36 (GMT)
committerJunio C Hamano <>2013-07-15 17:56:07 (GMT)
commit8f4f8f4579fe8cc630e118cc736de2b8d5cf8e34 (patch)
tree84c3f6e022bd7c4e81d05ca725a469e72806d00e /Documentation/technical/api-setup.txt
parentdad2586a6b30da902d5f1979221eccc474425a7a (diff)
guard against new pathspec magic in pathspec matching code
GUARD_PATHSPEC() marks pathspec-sensitive code, basically all those that touch anything in 'struct pathspec' except fields "nr" and "original". GUARD_PATHSPEC() is not supposed to fail. It's mainly to help the designers catch unsupported codepaths. Signed-off-by: Nguyễn Thái Ngọc Duy <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation/technical/api-setup.txt')
1 files changed, 19 insertions, 0 deletions
diff --git a/Documentation/technical/api-setup.txt b/Documentation/technical/api-setup.txt
index 90d1aff..540e455 100644
--- a/Documentation/technical/api-setup.txt
+++ b/Documentation/technical/api-setup.txt
@@ -28,3 +28,22 @@ parse_pathspec(). This function takes several arguments:
- 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