mirrors/git
1
0
Fork 0
mirror of https://github.com/git/git.git synced 2024-11-01 23:07:55 +01:00
Code Activity
git/Documentation/technical/api-directory-listing.txt

87 lines
2.1 KiB
Text
Raw Normal View History

Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 08:48:04 +01:00
directory listing API
=====================
The directory listing API is used to enumerate paths in the work tree,
optionally taking `.git/info/exclude` and `.gitignore` files per
directory into account.
Data structure
--------------
`struct dir_struct` structure is used to pass directory traversal
Improve documentation and comments regarding directory traversal API traversal API has a few potentially confusing properties. These comments clarify a few key aspects and will hopefully make it easier to understand for other newcomers in the future. Signed-off-by: Adam Spiers <git@adamspiers.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-12-27 03:32:21 +01:00
options to the library and to record the paths discovered. A single
`struct dir_struct` is used regardless of whether or not the traversal
recursively descends into subdirectories.
The notable options are:
Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 08:48:04 +01:00
`exclude_per_dir`::
The name of the file to be read in each directory for excluded
files (typically `.gitignore`).
api-directory-listing.txt: update to match code 7c4c97c0ac turned the flags in struct dir_struct into a single bitfield variable, but forgot to update this document. Signed-off-by: Adam Spiers <git@adamspiers.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-12-27 03:32:20 +01:00
`flags`::
Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 08:48:04 +01:00
api-directory-listing.txt: update to match code 7c4c97c0ac turned the flags in struct dir_struct into a single bitfield variable, but forgot to update this document. Signed-off-by: Adam Spiers <git@adamspiers.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-12-27 03:32:20 +01:00
A bit-field of options:
Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 08:48:04 +01:00
api-directory-listing.txt: update to match code 7c4c97c0ac turned the flags in struct dir_struct into a single bitfield variable, but forgot to update this document. Signed-off-by: Adam Spiers <git@adamspiers.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-12-27 03:32:20 +01:00
`DIR_SHOW_IGNORED`:::
Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 08:48:04 +01:00
The traversal is for finding just ignored files, not unignored
files.
api-directory-listing.txt: update to match code 7c4c97c0ac turned the flags in struct dir_struct into a single bitfield variable, but forgot to update this document. Signed-off-by: Adam Spiers <git@adamspiers.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-12-27 03:32:20 +01:00
`DIR_SHOW_OTHER_DIRECTORIES`:::
Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 08:48:04 +01:00
Include a directory that is not tracked.
api-directory-listing.txt: update to match code 7c4c97c0ac turned the flags in struct dir_struct into a single bitfield variable, but forgot to update this document. Signed-off-by: Adam Spiers <git@adamspiers.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-12-27 03:32:20 +01:00
`DIR_HIDE_EMPTY_DIRECTORIES`:::
Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 08:48:04 +01:00
Do not include a directory that is not tracked and is empty.
api-directory-listing.txt: update to match code 7c4c97c0ac turned the flags in struct dir_struct into a single bitfield variable, but forgot to update this document. Signed-off-by: Adam Spiers <git@adamspiers.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-12-27 03:32:20 +01:00
`DIR_NO_GITLINKS`:::
Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 08:48:04 +01:00
Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-21 20:17:53 +01:00
If set, recurse into a directory that looks like a Git
Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 08:48:04 +01:00
directory. Otherwise it is shown as a directory.
Improve documentation and comments regarding directory traversal API traversal API has a few potentially confusing properties. These comments clarify a few key aspects and will hopefully make it easier to understand for other newcomers in the future. Signed-off-by: Adam Spiers <git@adamspiers.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-12-27 03:32:21 +01:00
The result of the enumeration is left in these fields:
Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 08:48:04 +01:00
`entries[]`::
An array of `struct dir_entry`, each element of which describes
a path.
`nr`::
The number of members in `entries[]` array.
`alloc`::
Internal use; keeps track of allocation of `entries[]` array.
Calling sequence
----------------
Read .gitignore from index if it is skip-worktree This adds index as a prerequisite for directory listing (with exclude). At the moment directory listing is used by "git clean", "git add", "git ls-files" and "git status"/"git commit" and unpack_trees()-related commands. These commands have been checked/modified to populate index before doing directory listing. add_excludes_from_file() does not enable this feature, because it is used to read .git/info/exclude and some explicit files specified by "git ls-files". Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-08-20 15:47:01 +02:00
Note: index may be looked at for .gitignore files that are CE_SKIP_WORKTREE
marked. If you to exclude files, make sure you have loaded index first.
Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 08:48:04 +01:00
* Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0,
sizeof(dir))`.
dir.c: use a single struct exclude_list per source of excludes Previously each exclude_list could potentially contain patterns from multiple sources. For example dir->exclude_list[EXC_FILE] would typically contain patterns from .git/info/exclude and core.excludesfile, and dir->exclude_list[EXC_DIRS] could contain patterns from multiple per-directory .gitignore files during directory traversal (i.e. when dir->exclude_stack was more than one item deep). We split these composite exclude_lists up into three groups of exclude_lists (EXC_CMDL / EXC_DIRS / EXC_FILE as before), so that each exclude_list now contains patterns from a single source. This will allow us to cleanly track the origin of each pattern simply by adding a src field to struct exclude_list, rather than to struct exclude, which would make memory management of the source string tricky in the EXC_DIRS case where its contents are dynamically generated. Similarly, by moving the filebuf member from struct exclude_stack to struct exclude_list, it allows us to track and subsequently free memory buffers allocated during the parsing of all exclude files, rather than only tracking buffers allocated for files in the EXC_DIRS group. Signed-off-by: Adam Spiers <git@adamspiers.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-06 17:58:03 +01:00
* To add single exclude pattern, call `add_exclude_list()` and then
`add_exclude()`.
* To add patterns from a file (e.g. `.git/info/exclude`), call
`add_excludes_from_file()` , and/or set `dir.exclude_per_dir`. A
short-hand function `setup_standard_excludes()` can be used to set
up the standard set of exclude settings.
Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 08:48:04 +01:00
* Set options described in the Data Structure section above.
* Call `read_directory()`.
* Use `dir.entries[]`.
add git-check-ignore sub-command This works in a similar manner to git-check-attr. Thanks to Jeff King and Junio C Hamano for the idea: http://thread.gmane.org/gmane.comp.version-control.git/108671/focus=108815 Signed-off-by: Adam Spiers <git@adamspiers.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-06 17:58:13 +01:00
* Call `clear_directory()` when none of the contained elements are no longer in use.
dir.c: provide clear_directory() for reclaiming dir_struct memory By the end of a directory traversal, a dir_struct instance will typically contains pointers to various data structures on the heap. clear_directory() provides a convenient way to reclaim that memory. Signed-off-by: Adam Spiers <git@adamspiers.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-06 17:58:05 +01:00
Start preparing the API documents. Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-11-25 08:48:04 +01:00
(JC)
Copy permalink