path: root/Documentation/technical/api-setup.txt
diff options
authorNguyễn Thái Ngọc Duy <>2013-07-14 08:35:28 (GMT)
committerJunio C Hamano <>2013-07-15 17:56:06 (GMT)
commit87323bdace47c3d464a783f48b16617720e8eeee (patch)
tree8beed274243cecae03fcc0e3afa61be236865366 /Documentation/technical/api-setup.txt
parente4d92cdcd9450af7ae4c40de2b7c5c27a1faa138 (diff)
add parse_pathspec() that converts cmdline args to struct pathspec
Currently to fill a struct pathspec, we do: const char **paths; paths = get_pathspec(prefix, argv); ... init_pathspec(&pathspec, paths); "paths" can only carry bare strings, which loses information from command line arguments such as pathspec magic or the prefix part's length for each argument. parse_pathspec() is introduced to combine the two calls into one. The plan is gradually replace all get_pathspec() and init_pathspec() with parse_pathspec(). get_pathspec() now becomes a thin wrapper of parse_pathspec(). parse_pathspec() allows the caller to reject the pathspec magics that it does not support. When a new pathspec magic is introduced, we can enable it per command after making sure that all underlying code has no problem with the new magic. "flags" parameter is currently unused. But it would allow callers to pass certain instructions to parse_pathspec, for example forcing literal pathspec when no magic is used. With the introduction of parse_pathspec, there are now two functions that can initialize struct pathspec: init_pathspec and parse_pathspec. Any semantic changes in struct pathspec must be reflected in both functions. init_pathspec() will be phased out in favor of parse_pathspec(). 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, 18 insertions, 1 deletions
diff --git a/Documentation/technical/api-setup.txt b/Documentation/technical/api-setup.txt
index 4f63a04..90d1aff 100644
--- a/Documentation/technical/api-setup.txt
+++ b/Documentation/technical/api-setup.txt
@@ -8,6 +8,23 @@ Talk about
* is_inside_git_dir()
* is_inside_work_tree()
* setup_work_tree()
-* get_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.