git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
5269bb1c744c7a31f4d9ebb05c58ecb66e807d52 blob 3996 bytes (raw)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
in-core index API
=================

Reading API
-----------

`read_index()`::
	Read the whole index file from disk.

`index_name_pos(name, namelen)`::
	Find a cache_entry with name in the index.  Returns pos if an
	entry is matched exactly and -pos-1 if an entry is matched
	partially.
	e.g.
	index:
	file1
	file2
	path/file1
	zzz

	index_name_pos("path/file1", 10) returns 2, while
	index_name_pos("path", 4) returns -1

`read_index_filtered(opts)`::
	This method behaves differently for index-v2 and index-v5.

	For index-v2 it simply reads the whole index as read_index()
	does, so we are sure we don't have to reload anything if the
	user wants a different filter.  It also sets the filter_opts
	in the index_state, which is used to limit the results when
	iterating over the index with for_each_index_entry().

	The whole index is read to avoid the need to eventually
	re-read the index later, because the performance is no
	different when reading it partially.

	For index-v5 it creates an adjusted_pathspec to filter the
	reading.  First all the directory entries are read and then
	the cache_entries in the directories that match the adjusted
	pathspec are read.  The filter_opts in the index_state are set
	to filter out the rest of the cache_entries that are matched
	by the adjusted pathspec but not by the pathspec given.  The
	rest of the index entries are filtered out when iterating over
	the cache with for_each_index_entries.

`get_index_entry_by_name(name, namelen, &ce)`::
	Returns a cache_entry matched by the name, returned via the
	&ce parameter.  If a cache entry is matched exactly, 1 is
	returned, otherwise 0.  For an example see index_name_pos().
	This function should be used instead of the index_name_pos()
	function to retrieve cache entries.

`for_each_index_entry(fn, cb_data)`::
	Iterates over all cache_entries in the index filtered by
	filter_opts in the index_stat.  For each cache entry fn is
	executed with cb_data as callback data.  From within the loop
	do `return 0` to continue, or `return 1` to break the loop.

`next_index_entry(ce)`::
	Returns the cache_entry that follows after ce

`index_change_filter_opts(opts)`::
	This function again has a slightly different functionality for
	index-v2 and index-v5.

	For index-v2 it simply changes the filter_opts, so
	for_each_index_entry uses the changed index_opts, to iterate
	over a different set of cache entries.

	For index-v5 it refreshes the index if the filter_opts have
	changed and sets the new filter_opts in the index state, again
	to iterate over a different set of cache entries as with
	index-v2.

	This has some optimization potential, in the case that the
	opts get stricter (less of the index should be read) it
	doesn't have to reload anything, but currently does.

Using the new index api
-----------------------

Currently loops over a specific set of index entry were written as:
  i = start_index;
  while (i < active_nr) { ce = active_cache[i]; do(something); i++; }

they should be rewritten to:
  ce = start;
  while (ce) { do(something); ce = next_cache_entry(ce); }

which is the equivalent operation but hides the in-memory format of
the index from the user.

For getting a cache entry get_cache_entry_by_name() should be used
instead of cache_name_pos(). e.g.:
  int pos = cache_name_pos(name, namelen);
  struct cache_entry *ce = active_cache[pos];
  if (pos < 0) { do(something) }
  else { do(somethingelse) }

should be written as:
  struct cache_entry *ce;
  int ret = get_cache_entry_by_name(name, namelen, &ce);
  if (!ret) { do(something) }
  else { do(somethingelse) }

TODO
----
Talk about <read-cache.c> and <cache-tree.c>, things like:

* cache -> the_index macros
* write_index()
* ie_match_stat() and ie_modified(); how they are different and when to
  use which.
* remove_index_entry_at()
* remove_file_from_index()
* add_file_to_index()
* add_index_entry()
* refresh_index()
* discard_index()
* cache_tree_invalidate_path()
* cache_tree_update()



(JC, Linus)
debug log:

solving 5269bb1 ...
found 5269bb1 in https://public-inbox.org/git/871u78rcw0.fsf@gmail.com/
found adbdbf5 in git.git.git
preparing index
index prepared:
100644 adbdbf5d75d8e17e38e1ba0e3694b4ff210f5799	Documentation/technical/api-in-core-index.txt

applying [1/1] https://public-inbox.org/git/871u78rcw0.fsf@gmail.com/
diff --git a/Documentation/technical/api-in-core-index.txt b/Documentation/technical/api-in-core-index.txt
index adbdbf5..5269bb1 100644

Checking patch Documentation/technical/api-in-core-index.txt...
Applied patch Documentation/technical/api-in-core-index.txt cleanly.

index at:
100644 5269bb1c744c7a31f4d9ebb05c58ecb66e807d52	Documentation/technical/api-in-core-index.txt

git@vger.kernel.org list mirror (unofficial, one of many)

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 git git/ https://public-inbox.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.version-control.git
	nntp://ie5yzdi7fg72h7s4sdcztq5evakq23rdt33mfyfcddc5u3ndnw24ogqd.onion/inbox.comp.version-control.git
	nntp://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/inbox.comp.version-control.git
	nntp://news.gmane.io/gmane.comp.version-control.git
 note: .onion URLs require Tor: https://www.torproject.org/

code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git