← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/fetch.txt

  • Committer: Jelmer Vernooij
  • Date: 2011-03-12 16:55:08 UTC
  • mto: This revision was merged to the branch mainline in revision 5737.
  • Revision ID: jelmer@samba.org-20110312165508-8aerwldchcf1n2ah
Test default control component format implementation.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/fetch.txt
 
1
=============
 
2
Fetching data
 
3
=============
 
4
 
 
5
Overview of a fetch
 
6
===================
 
7
 
 
8
Inside bzr, a typical fetch happens like this:
 
9
 
 
10
* a user runs a command like ``bzr branch`` or ``bzr pull``
 
11
 
 
12
* ``Repository.fetch`` is called (by a higher-level method such as
 
13
  ``ControlDir.sprout``, ``Branch.fetch``, etc).
 
14
 
 
15
* An ``InterRepository`` object is created.  The exact implementation of
 
16
  ``InterRepository`` chosen depends on the format/capabilities of the
 
17
  source and target repos.
 
18
 
 
19
* The source and target repositories are compared to determine which data
 
20
  needs to be transferred.
 
21
 
 
22
* The repository data is copied.  Often this is done by creating a
 
23
  ``StreamSource`` and ``StreamSink`` from the source and target
 
24
  repositories and feeding the stream from the source into the sink, but
 
25
  some ``InterRepository`` implementations do differently.
 
26
 
 
27
 
 
28
How objects to be transferred are determined
 
29
============================================
 
30
 
 
31
See ``InterRepository._walk_to_common_revisions``.  The basic idea is to
 
32
do a breadth-first search in the source repository's revision graph
 
33
(starting from the head or heads the caller asked for), and look in the
 
34
target repository to see if those revisions are already present.
 
35
Eventually this will find the common ancestors in both graphs, and thus
 
36
the set of revisions to be copied has been identified.
 
37
 
 
38
All inventories for the copied revisions need to be present (and all
 
39
parent inventories at the stacking boundary too, to support stacking).
 
40
 
 
41
All texts versions introduced by those inventories need to be transferred
 
42
(but see also stacking constraints).
 
43
 
 
44
Fetch specs
 
45
===========
 
46
 
 
47
The most ``fetch`` methods accept a ``fetch_spec`` parameter.  This is how
 
48
the caller controls what is fetched: e.g. all revisions for a given head
 
49
(that aren't already present in the target), the full ancestry for one or
 
50
more heads, or even the full contents of the source repository.
 
51
 
 
52
The ``fetch_spec`` parameter is an object that implements the interface
 
53
defined by ``AbstractSearchResult`` in ``bzrlib.graph``.  It describes
 
54
which keys should be fetched.  Current implementations are
 
55
``SearchResult``, ``PendingAncestryResult``, ``EmptySearchResult``, and
 
56
``EverythingResult``.  Some have options controlling if missing revisions
 
57
cause errors or not, etc.
 
58
 
 
59
There are also some “search” objects, which can be used to conveniently
 
60
construct a search result for common cases: ``EverythingNotInOther`` and
 
61
``NotInOtherForRevs``.  They provide an ``execute`` method that performs
 
62
the search and returns a search result.
 
63
 
 
64
Also, ``Graph._make_breadth_first_searcher`` returns an object with a
 
65
``get_result`` method that returns a search result.
 
66
 
 
67
 
 
68
Streams
 
69
=======
 
70
 
 
71
A **stream** is an iterable of (substream type, substream) pairs.
 
72
The **substream type** is a ``str`` that will be one of ``texts``,
 
73
``inventories``, ``inventory-deltas``, ``chk_bytes``, ``revisions`` or
 
74
``signatures``.  A **substream** is a record stream.  The format of those
 
75
records depends on the repository format being streamed, except for
 
76
``inventory-deltas`` records which are format-independent.
 
77
 
 
78
A stream source can be constructed with ``repo._get_source(to_format)``,
 
79
and it provides a ``get_stream(search)`` method (among others).  A stream
 
80
sink can be constructed with ``repo._get_sink()``, and provides an
 
81
``insert_stream(stream, src_format, resume_tokens)`` method (among
 
82
others).
 
83
 
 
84
 
 
85
..
 
86
   vim: ft=rst tw=74 ai