1# Copyright (C) 2006-2011 Canonical Ltd 2# 3# This program is free software; you can redistribute it and/or modify 4# it under the terms of the GNU General Public License as published by 5# the Free Software Foundation; either version 2 of the License, or 6# (at your option) any later version. 7# 8# This program is distributed in the hope that it will be useful, 9# but WITHOUT ANY WARRANTY; without even the implied warranty of 10# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 11# GNU General Public License for more details. 12# 13# You should have received a copy of the GNU General Public License 14# along with this program; if not, write to the Free Software 15# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 16 17"""MutableTree object. 18 19See MutableTree for more details. 20""" 21 22from . import ( 23 errors, 24 hooks, 25 osutils, 26 trace, 27 tree, 28 ) 29 30 31 32class BadReferenceTarget(errors.InternalBzrError): 33 34 _fmt = "Can't add reference to %(other_tree)s into %(tree)s." \ 35 "%(reason)s" 36 37 def __init__(self, tree, other_tree, reason): 38 self.tree = tree 39 self.other_tree = other_tree 40 self.reason = reason 41 42 43class MutableTree(tree.Tree): 44 """A MutableTree is a specialisation of Tree which is able to be mutated. 45 46 Generally speaking these mutations are only possible within a lock_write 47 context, and will revert if the lock is broken abnormally - but this cannot 48 be guaranteed - depending on the exact implementation of the mutable state. 49 50 The most common form of Mutable Tree is WorkingTree, see breezy.workingtree. 51 For tests we also have MemoryTree which is a MutableTree whose contents are 52 entirely in memory. 53 54 For now, we are not treating MutableTree as an interface to provide 55 conformance tests for - rather we are testing MemoryTree specifically, and 56 interface testing implementations of WorkingTree. 57 58 A mutable tree always has an associated Branch and ControlDir object - the 59 branch and bzrdir attributes. 60 """ 61 62 def __init__(self, *args, **kw): 63 super(MutableTree, self).__init__(*args, **kw) 64 # Is this tree on a case-insensitive or case-preserving file-system? 65 # Sub-classes may initialize to False if they detect they are being 66 # used on media which doesn't differentiate the case of names. 67 self.case_sensitive = True 68 69 def is_control_filename(self, filename): 70 """True if filename is the name of a control file in this tree. 71 72 :param filename: A filename within the tree. This is a relative path 73 from the root of this tree. 74 75 This is true IF and ONLY IF the filename is part of the meta data 76 that bzr controls in this tree. I.E. a random .bzr directory placed 77 on disk will not be a control file for this tree. 78 """ 79 raise NotImplementedError(self.is_control_filename) 80 81 def add(self, files, ids=None, kinds=None): 82 """Add paths to the set of versioned paths. 83 84 Note that the command line normally calls smart_add instead, 85 which can automatically recurse. 86 87 This adds the files to the tree, so that they will be 88 recorded by the next commit. 89 90 :param files: List of paths to add, relative to the base of the tree. 91 :param ids: If set, use these instead of automatically generated ids. 92 Must be the same length as the list of files, but may 93 contain None for ids that are to be autogenerated. 94 :param kinds: Optional parameter to specify the kinds to be used for 95 each file. 96 97 TODO: Perhaps callback with the ids and paths as they're added. 98 """ 99 if isinstance(files, str): 100 # XXX: Passing a single string is inconsistent and should be 101 # deprecated. 102 if not (ids is None or isinstance(ids, bytes)): 103 raise AssertionError() 104 if not (kinds is None or isinstance(kinds, str)): 105 raise AssertionError() 106 files = [files] 107 if ids is not None: 108 ids = [ids] 109 if kinds is not None: 110 kinds = [kinds] 111 112 files = [path.strip('/') for path in files] 113 114 if ids is None: 115 ids = [None] * len(files) 116 else: 117 if not (len(ids) == len(files)): 118 raise AssertionError() 119 if kinds is None: 120 kinds = [None] * len(files) 121 elif not len(kinds) == len(files): 122 raise AssertionError() 123 with self.lock_tree_write(): 124 for f in files: 125 # generic constraint checks: 126 if self.is_control_filename(f): 127 raise errors.ForbiddenControlFileError(filename=f) 128 fp = osutils.splitpath(f) 129 # fill out file kinds for all files [not needed when we stop 130 # caring about the instantaneous file kind within a uncommmitted tree 131 # 132 self._gather_kinds(files, kinds) 133 self._add(files, ids, kinds) 134 135 def add_reference(self, sub_tree): 136 """Add a TreeReference to the tree, pointing at sub_tree. 137 138 :param sub_tree: subtree to add. 139 """ 140 raise errors.UnsupportedOperation(self.add_reference, self) 141 142 def _add(self, files, ids, kinds): 143 """Helper function for add - updates the inventory. 144 145 :param files: sequence of pathnames, relative to the tree root 146 :param ids: sequence of suggested ids for the files (may be None) 147 :param kinds: sequence of inventory kinds of the files (i.e. may 148 contain "tree-reference") 149 """ 150 raise NotImplementedError(self._add) 151 152 def commit(self, message=None, revprops=None, *args, **kwargs): 153 # avoid circular imports 154 from breezy import commit 155 possible_master_transports = [] 156 with self.lock_write(): 157 revprops = commit.Commit.update_revprops( 158 revprops, 159 self.branch, 160 kwargs.pop('authors', None), 161 kwargs.get('local', False), 162 possible_master_transports) 163 # args for wt.commit start at message from the Commit.commit method, 164 args = (message, ) + args 165 for hook in MutableTree.hooks['start_commit']: 166 hook(self) 167 committed_id = commit.Commit().commit(working_tree=self, 168 revprops=revprops, 169 possible_master_transports=possible_master_transports, 170 *args, **kwargs) 171 post_hook_params = PostCommitHookParams(self) 172 for hook in MutableTree.hooks['post_commit']: 173 hook(post_hook_params) 174 return committed_id 175 176 def _gather_kinds(self, files, kinds): 177 """Helper function for add - sets the entries of kinds.""" 178 raise NotImplementedError(self._gather_kinds) 179 180 def has_changes(self, _from_tree=None): 181 """Quickly check that the tree contains at least one commitable change. 182 183 :param _from_tree: tree to compare against to find changes (default to 184 the basis tree and is intended to be used by tests). 185 186 :return: True if a change is found. False otherwise 187 """ 188 raise NotImplementedError(self.has_changes) 189 190 def check_changed_or_out_of_date(self, strict, opt_name, 191 more_error, more_warning): 192 """Check the tree for uncommitted changes and branch synchronization. 193 194 If strict is None and not set in the config files, a warning is issued. 195 If strict is True, an error is raised. 196 If strict is False, no checks are done and no warning is issued. 197 198 :param strict: True, False or None, searched in branch config if None. 199 200 :param opt_name: strict option name to search in config file. 201 202 :param more_error: Details about how to avoid the check. 203 204 :param more_warning: Details about what is happening. 205 """ 206 with self.lock_read(): 207 if strict is None: 208 strict = self.branch.get_config_stack().get(opt_name) 209 if strict is not False: 210 err_class = None 211 if self.has_changes(): 212 err_class = errors.UncommittedChanges 213 elif self.last_revision() != self.branch.last_revision(): 214 # The tree has lost sync with its branch, there is little 215 # chance that the user is aware of it but he can still 216 # force the action with --no-strict 217 err_class = errors.OutOfDateTree 218 if err_class is not None: 219 if strict is None: 220 err = err_class(self, more=more_warning) 221 # We don't want to interrupt the user if he expressed 222 # no preference about strict. 223 trace.warning('%s', err._format()) 224 else: 225 err = err_class(self, more=more_error) 226 raise err 227 228 def last_revision(self): 229 """Return the revision id of the last commit performed in this tree. 230 231 In early tree formats the result of last_revision is the same as the 232 branch last_revision, but that is no longer the case for modern tree 233 formats. 234 235 last_revision returns the left most parent id, or None if there are no 236 parents. 237 238 last_revision was deprecated as of 0.11. Please use get_parent_ids 239 instead. 240 """ 241 raise NotImplementedError(self.last_revision) 242 243 def lock_tree_write(self): 244 """Lock the working tree for write, and the branch for read. 245 246 This is useful for operations which only need to mutate the working 247 tree. Taking out branch write locks is a relatively expensive process 248 and may fail if the branch is on read only media. So branch write locks 249 should only be taken out when we are modifying branch data - such as in 250 operations like commit, pull, uncommit and update. 251 """ 252 raise NotImplementedError(self.lock_tree_write) 253 254 def lock_write(self): 255 """Lock the tree and its branch. This allows mutating calls to be made. 256 257 Some mutating methods will take out implicit write locks, but in 258 general you should always obtain a write lock before calling mutating 259 methods on a tree. 260 """ 261 raise NotImplementedError(self.lock_write) 262 263 def mkdir(self, path, file_id=None): 264 """Create a directory in the tree. if file_id is None, one is assigned. 265 266 :param path: A unicode file path. 267 :param file_id: An optional file-id. 268 :return: the file id of the new directory. 269 """ 270 raise NotImplementedError(self.mkdir) 271 272 def _observed_sha1(self, path, sha_and_stat): 273 """Tell the tree we have observed a paths sha1. 274 275 The intent of this function is to allow trees that have a hashcache to 276 update the hashcache during commit. If the observed file is too new 277 (based on the stat_value) to be safely hash-cached the tree will ignore 278 it. 279 280 The default implementation does nothing. 281 282 :param path: The file path 283 :param sha_and_stat: The sha 1 and stat result observed. 284 :return: None 285 """ 286 287 def put_file_bytes_non_atomic(self, path, bytes): 288 """Update the content of a file in the tree. 289 290 Note that the file is written in-place rather than being 291 written to a temporary location and renamed. As a consequence, 292 readers can potentially see the file half-written. 293 294 :param file_id: file-id of the file 295 :param bytes: the new file contents 296 """ 297 raise NotImplementedError(self.put_file_bytes_non_atomic) 298 299 def set_parent_ids(self, revision_ids, allow_leftmost_as_ghost=False): 300 """Set the parents ids of the working tree. 301 302 :param revision_ids: A list of revision_ids. 303 """ 304 raise NotImplementedError(self.set_parent_ids) 305 306 def set_parent_trees(self, parents_list, allow_leftmost_as_ghost=False): 307 """Set the parents of the working tree. 308 309 :param parents_list: A list of (revision_id, tree) tuples. 310 If tree is None, then that element is treated as an unreachable 311 parent tree - i.e. a ghost. 312 """ 313 raise NotImplementedError(self.set_parent_trees) 314 315 def smart_add(self, file_list, recurse=True, action=None, save=True): 316 """Version file_list, optionally recursing into directories. 317 318 This is designed more towards DWIM for humans than API clarity. 319 For the specific behaviour see the help for cmd_add(). 320 321 :param file_list: List of zero or more paths. *NB: these are 322 interpreted relative to the process cwd, not relative to the 323 tree.* (Add and most other tree methods use tree-relative 324 paths.) 325 :param action: A reporter to be called with the working tree, parent_ie, 326 path and kind of the path being added. It may return a file_id if 327 a specific one should be used. 328 :param save: Save the changes after completing the adds. If False 329 this provides dry-run functionality by doing the add and not saving 330 the changes. 331 :return: A tuple - files_added, ignored_files. files_added is the count 332 of added files, and ignored_files is a dict mapping files that were 333 ignored to the rule that caused them to be ignored. 334 """ 335 raise NotImplementedError(self.smart_add) 336 337 def rename_one(self, from_rel, to_rel, after=False): 338 """Rename one file. 339 340 This can change the directory or the filename or both. 341 342 rename_one has several 'modes' to work. First, it can rename a physical 343 file and change the file_id. That is the normal mode. Second, it can 344 only change the file_id without touching any physical file. 345 346 rename_one uses the second mode if 'after == True' and 'to_rel' is 347 either not versioned or newly added, and present in the working tree. 348 349 rename_one uses the second mode if 'after == False' and 'from_rel' is 350 versioned but no longer in the working tree, and 'to_rel' is not 351 versioned but present in the working tree. 352 353 rename_one uses the first mode if 'after == False' and 'from_rel' is 354 versioned and present in the working tree, and 'to_rel' is not 355 versioned and not present in the working tree. 356 357 Everything else results in an error. 358 """ 359 raise NotImplementedError(self.rename_one) 360 361 def copy_one(self, from_rel, to_rel): 362 """Copy one file or directory. 363 364 This can change the directory or the filename or both. 365 366 """ 367 raise NotImplementedError(self.copy_one) 368 369 def transform(self, pb=None): 370 """Return a transform object for use with this tree.""" 371 raise NotImplementedError(self.transform) 372 373 374class MutableTreeHooks(hooks.Hooks): 375 """A dictionary mapping a hook name to a list of callables for mutabletree 376 hooks. 377 """ 378 379 def __init__(self): 380 """Create the default hooks. 381 382 """ 383 hooks.Hooks.__init__(self, "breezy.mutabletree", "MutableTree.hooks") 384 self.add_hook('start_commit', 385 "Called before a commit is performed on a tree. The start commit " 386 "hook is able to change the tree before the commit takes place. " 387 "start_commit is called with the breezy.mutabletree.MutableTree " 388 "that the commit is being performed on.", (1, 4)) 389 self.add_hook('post_commit', 390 "Called after a commit is performed on a tree. The hook is " 391 "called with a breezy.mutabletree.PostCommitHookParams object. " 392 "The mutable tree the commit was performed on is available via " 393 "the mutable_tree attribute of that object.", (2, 0)) 394 self.add_hook('pre_transform', 395 "Called before a tree transform on this tree. The hook is called " 396 "with the tree that is being transformed and the transform.", 397 (2, 5)) 398 self.add_hook('post_build_tree', 399 "Called after a completely new tree is built. The hook is " 400 "called with the tree as its only argument.", (2, 5)) 401 self.add_hook('post_transform', 402 "Called after a tree transform has been performed on a tree. " 403 "The hook is called with the tree that is being transformed and " 404 "the transform.", 405 (2, 5)) 406 407 408# install the default hooks into the MutableTree class. 409MutableTree.hooks = MutableTreeHooks() 410 411 412class PostCommitHookParams(object): 413 """Parameters for the post_commit hook. 414 415 To access the parameters, use the following attributes: 416 417 * mutable_tree - the MutableTree object 418 """ 419 420 def __init__(self, mutable_tree): 421 """Create the parameters for the post_commit hook.""" 422 self.mutable_tree = mutable_tree 423