git/Documentation/technical/api-setup.txt
Brandon Williams 34305f7753 pathspec: remove the deprecated get_pathspec function
Now that all callers of the old 'get_pathspec' interface have been
migrated to use the new pathspec struct interface it can be removed
from the codebase.

Since there are no more users of the '_raw' field in the pathspec struct
it can also be removed.  This patch also removes the old functionality
of modifying the const char **argv array that was passed into
parse_pathspec.  Instead the constructed 'match' string (which is a
pathspec element with the prefix prepended) is only stored in its
corresponding pathspec_item entry.

Signed-off-by: Brandon Williams <bmwill@google.com>
Reviewed-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-01-08 18:04:17 -08:00

48 lines
1.6 KiB
Plaintext

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
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.