← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/status.txt

  • Committer: Vincent Ladeuil
  • Date: 2013-08-09 15:09:23 UTC
  • mto: This revision was merged to the branch mainline in revision 6587.
  • Revision ID: v.ladeuil+lp@free.fr-20130809150923-y71dusyorep0hbkt
Fix various typos in docstrings. Rename 'buffer' to 'buf' since it's now a python builtin function.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/status.txt
 
1
The status command
 
2
==================
 
3
 
 
4
The status command is used to provide a pithy listing of the changes between
 
5
two trees. Its common case is between the working tree and the basis tree, but
 
6
it can be used between any two arbitrary trees.
 
7
 
 
8
.. contents:: :local:
 
9
 
 
10
UI Overview
 
11
-----------
 
12
 
 
13
Status shows several things in parallel (for the paths the user supplied mapped
 
14
across the from and to tree, and any pending merges in the to tree).
 
15
 
 
16
1. Single line summary of all new revisions - the pending merges and their
 
17
   parents recursively.
 
18
2. Changes to the tree shape - adds/deletes/renames.
 
19
3. Changes to versioned content - kind changes and content changes.
 
20
4. Unknown files in the to tree.
 
21
5. Files with conflicts in the to tree.
 
22
 
 
23
 
 
24
Ideal work for working tree to historical status
 
25
------------------------------------------------
 
26
 
 
27
We need to do the following things at a minimum:
 
28
 
 
29
1. Determine new revisions - the pending merges and history.
 
30
 
 
31
1. Retrieve the first line of the commit message for the new revisions.
 
32
 
 
33
1. Determine the tree differences between the two trees using the users paths
 
34
   to limit the scope, and resolving paths in the trees for any pending merges.
 
35
   We arguably don't care about tracking metadata for this - only the value of
 
36
   the tree the user commited.
 
37
 
 
38
1. The entire contents of directories which are versioned when showing
 
39
   unknowns.
 
40
 
 
41
1. Whether a given unversioned path is unknown or ignored.
 
42
 
 
43
1. The list conflicted paths in the tree (which match the users path
 
44
   selection?)
 
45
 
 
46
 
 
47
Expanding on the tree difference case we will need to:
 
48
 
 
49
1. Stat every path in working trees which is included by the users path
 
50
   selection to ascertain kind and execute bit.
 
51
 
 
52
1. For paths which have the same kind in both trees and have content, read
 
53
   that content or otherwise determine whether the content has changed. Using
 
54
   our hash cache from the dirstate allows us to avoid reading the file in the
 
55
   common case. There are alternative ways to achieve this - we could record
 
56
   a pointer to a revision which contained this fileid with the current content
 
57
   rather than storing the content's hash; but this seems to be a pointless
 
58
   double-indirection unless we save enough storage in the working tree. A
 
59
   variation of this is to not record an explicit pointer but instead
 
60
   define an implicit pointer as being to the left-hand-parent tree.
 
61
 
 
62
 
 
63
Locality of reference
 
64
---------------------
 
65
 
 
66
- We should stat files in the same directory without reading or statting
 
67
  files in other directories. That is we should do all the statting we
 
68
  intend to do within a given directory without doing any other IO, to
 
69
  minimise pressure on the drive heads to seek.
 
70
 
 
71
- We should read files in the same directory without reading or writing
 
72
  files in other directories - and note this is separate to statting (file
 
73
  data is usually physically disjoint to metadata).
 
74
 
 
75
 
 
76
Scaling observations
 
77
--------------------
 
78
 
 
79
- The stat operation clearly involves every versioned path in the common case.
 
80
- Expanding out the users path selection in a naive manner involves reading the
 
81
  entire tree shape information for both trees and for all pending-merge trees.
 
82
  (Dirstate makes this tolerably cheap for now, but we're still scaling
 
83
  extra-linearly.)
 
84
- The amount of effort required to generate tree differences between the
 
85
  working tree and the basis tree is interesting: with a tree-like structure
 
86
  and some generatable name for child nodes we use the working tree data to
 
87
  eliminate accessing or considering subtrees regardless of historival
 
88
  age. However, if we have had to access the historical tree shape to
 
89
  perform path selection this rather reduces the win we can obtain here.
 
90
  If we can cause path expansion to not require historical shape access
 
91
  (perhaps by performing the expansion after calculating the tree
 
92
  difference for the top level of the selected path) then we can gain a
 
93
  larger win. This strongly suggests that path expansion and tree
 
94
  difference generation should be linked in terms of API.
 
95
 
 
96
 
 
97
 
 
98
..
 
99
   vim: ft=rst tw=74 ai
 
100