<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>The status command — Bazaar 2.7.0 documentation</title> <link rel="stylesheet" href="_static/classic.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/underscore.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> <script type="text/javascript" src="_static/language_data.js"></script> <link rel="shortcut icon" href="_static/bzr.ico"/> <link rel="search" title="Search" href="search.html" /> <link rel="stylesheet" href="_static/bzr-doc.css" type="text/css" /> </head><body> <div class="related" role="navigation" aria-label="related navigation"> <h3>Navigation</h3> <ul> <li><a href="http://bazaar.canonical.com/"> <img src="_static/bzr icon 16.png" /> Home</a> | </li> <a href="http://doc.bazaar.canonical.com/en/">Documentation</a> | </li> <li class="nav-item nav-item-0"><a href="index.html">Developer Document Catalog (2.7.0)</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <div class="section" id="the-status-command"> <h1>The status command<a class="headerlink" href="#the-status-command" title="Permalink to this headline">¶</a></h1> <p>The status command is used to provide a pithy listing of the changes between two trees. Its common case is between the working tree and the basis tree, but it can be used between any two arbitrary trees.</p> <div class="contents local topic" id="contents"> <ul class="simple"> <li><a class="reference internal" href="#ui-overview" id="id1">UI Overview</a></li> <li><a class="reference internal" href="#ideal-work-for-working-tree-to-historical-status" id="id2">Ideal work for working tree to historical status</a></li> <li><a class="reference internal" href="#locality-of-reference" id="id3">Locality of reference</a></li> <li><a class="reference internal" href="#scaling-observations" id="id4">Scaling observations</a></li> </ul> </div> <div class="section" id="ui-overview"> <h2><a class="toc-backref" href="#id1">UI Overview</a><a class="headerlink" href="#ui-overview" title="Permalink to this headline">¶</a></h2> <p>Status shows several things in parallel (for the paths the user supplied mapped across the from and to tree, and any pending merges in the to tree).</p> <ol class="arabic simple"> <li>Single line summary of all new revisions - the pending merges and their parents recursively.</li> <li>Changes to the tree shape - adds/deletes/renames.</li> <li>Changes to versioned content - kind changes and content changes.</li> <li>Unknown files in the to tree.</li> <li>Files with conflicts in the to tree.</li> </ol> </div> <div class="section" id="ideal-work-for-working-tree-to-historical-status"> <h2><a class="toc-backref" href="#id2">Ideal work for working tree to historical status</a><a class="headerlink" href="#ideal-work-for-working-tree-to-historical-status" title="Permalink to this headline">¶</a></h2> <p>We need to do the following things at a minimum:</p> <ol class="arabic simple"> <li>Determine new revisions - the pending merges and history.</li> </ol> <ol class="arabic simple"> <li>Retrieve the first line of the commit message for the new revisions.</li> </ol> <ol class="arabic simple"> <li>Determine the tree differences between the two trees using the users paths to limit the scope, and resolving paths in the trees for any pending merges. We arguably don’t care about tracking metadata for this - only the value of the tree the user commited.</li> </ol> <ol class="arabic simple"> <li>The entire contents of directories which are versioned when showing unknowns.</li> </ol> <ol class="arabic simple"> <li>Whether a given unversioned path is unknown or ignored.</li> </ol> <ol class="arabic simple"> <li>The list conflicted paths in the tree (which match the users path selection?)</li> </ol> <p>Expanding on the tree difference case we will need to:</p> <ol class="arabic simple"> <li>Stat every path in working trees which is included by the users path selection to ascertain kind and execute bit.</li> </ol> <ol class="arabic simple"> <li>For paths which have the same kind in both trees and have content, read that content or otherwise determine whether the content has changed. Using our hash cache from the dirstate allows us to avoid reading the file in the common case. There are alternative ways to achieve this - we could record a pointer to a revision which contained this fileid with the current content rather than storing the content’s hash; but this seems to be a pointless double-indirection unless we save enough storage in the working tree. A variation of this is to not record an explicit pointer but instead define an implicit pointer as being to the left-hand-parent tree.</li> </ol> </div> <div class="section" id="locality-of-reference"> <h2><a class="toc-backref" href="#id3">Locality of reference</a><a class="headerlink" href="#locality-of-reference" title="Permalink to this headline">¶</a></h2> <ul class="simple"> <li>We should stat files in the same directory without reading or statting files in other directories. That is we should do all the statting we intend to do within a given directory without doing any other IO, to minimise pressure on the drive heads to seek.</li> <li>We should read files in the same directory without reading or writing files in other directories - and note this is separate to statting (file data is usually physically disjoint to metadata).</li> </ul> </div> <div class="section" id="scaling-observations"> <h2><a class="toc-backref" href="#id4">Scaling observations</a><a class="headerlink" href="#scaling-observations" title="Permalink to this headline">¶</a></h2> <ul class="simple"> <li>The stat operation clearly involves every versioned path in the common case.</li> <li>Expanding out the users path selection in a naive manner involves reading the entire tree shape information for both trees and for all pending-merge trees. (Dirstate makes this tolerably cheap for now, but we’re still scaling extra-linearly.)</li> <li>The amount of effort required to generate tree differences between the working tree and the basis tree is interesting: with a tree-like structure and some generatable name for child nodes we use the working tree data to eliminate accessing or considering subtrees regardless of historival age. However, if we have had to access the historical tree shape to perform path selection this rather reduces the win we can obtain here. If we can cause path expansion to not require historical shape access (perhaps by performing the expansion after calculating the tree difference for the top level of the selected path) then we can gain a larger win. This strongly suggests that path expansion and tree difference generation should be linked in terms of API.</li> </ul> </div> </div> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebarwrapper"> <h3><a href="index.html">Table of Contents</a></h3> <ul> <li><a class="reference internal" href="#">The status command</a><ul> <li><a class="reference internal" href="#ui-overview">UI Overview</a></li> <li><a class="reference internal" href="#ideal-work-for-working-tree-to-historical-status">Ideal work for working tree to historical status</a></li> <li><a class="reference internal" href="#locality-of-reference">Locality of reference</a></li> <li><a class="reference internal" href="#scaling-observations">Scaling observations</a></li> </ul> </li> </ul> <div role="note" aria-label="source link"> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="_sources/status.txt" rel="nofollow">Show Source</a></li> </ul> </div> <div id="searchbox" style="display: none" role="search"> <h3>Quick search</h3> <div class="searchformwrapper"> <form class="search" action="search.html" method="get"> <input type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related" role="navigation" aria-label="related navigation"> <h3>Navigation</h3> <ul> <li><a href="http://bazaar.canonical.com/"> <img src="_static/bzr icon 16.png" /> Home</a> | </li> <a href="http://doc.bazaar.canonical.com/en/">Documentation</a> | </li> <li class="nav-item nav-item-0"><a href="index.html">Developer Document Catalog (2.7.0)</a> »</li> </ul> </div> <div class="footer" role="contentinfo"> © Copyright 2009-2011 Canonical Ltd. Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4. </div> </body> </html>