/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to bzrlib/builtins.py

merge log help improvements

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/builtins.py
1819
1819
 
1820
1820
 
1821
1821
class cmd_log(Command):
1822
 
    """Show log of a branch, file, or directory.
1823
 
 
1824
 
    By default show the log of the branch containing the working directory.
1825
 
 
1826
 
    To request a range of logs, you can use the command -r begin..end
1827
 
    -r revision requests a specific revision, -r ..end or -r begin.. are
1828
 
    also valid.
1829
 
 
1830
 
    :Examples:
1831
 
        Log the current branch::
1832
 
 
1833
 
            bzr log
1834
 
 
1835
 
        Log a file::
1836
 
 
1837
 
            bzr log foo.c
1838
 
 
1839
 
        Log the last 10 revisions of a branch::
1840
 
 
1841
 
            bzr log -r -10.. http://server/branch
 
1822
    """Show historical log for a branch or subset of a branch.
 
1823
 
 
1824
    log is bzr's default tool for exploring the history of a branch.
 
1825
    The branch to use is taken from the first parameter. If no parameters
 
1826
    are given, the branch containing the working directory is logged.
 
1827
    Here are some simple examples::
 
1828
 
 
1829
      bzr log                       log the current branch
 
1830
      bzr log foo.py                log a file in its branch
 
1831
      bzr log http://server/branch  log a branch on a server
 
1832
 
 
1833
    The filtering, ordering and information shown for each revision can
 
1834
    be controlled as explained below. By default, all revisions are
 
1835
    shown sorted (topologically) so that newer revisions appear before
 
1836
    older ones and descendants always appear before ancestors. If displayed,
 
1837
    merged revisions are shown indented under the revision in which they
 
1838
    were merged.
 
1839
 
 
1840
    :Output control:
 
1841
 
 
1842
      The log format controls how information about each revision is
 
1843
      displayed. The standard log formats are called ``long``, ``short``
 
1844
      and ``line``. The default is long. See ``bzr help log-formats``
 
1845
      for more details on log formats.
 
1846
 
 
1847
      The following options can be used to control what information is
 
1848
      displayed::
 
1849
  
 
1850
        -l N        display a maximum of N revisions
 
1851
        -n N        display N levels of revisions (0 for all, 1 for collapsed)
 
1852
        -v          display a status summary (delta) for each revision
 
1853
        -p          display a diff (patch) for each revision
 
1854
        --show-ids  display revision-ids (and file-ids), not just revnos
 
1855
  
 
1856
      Note that the default number of levels to display is a function of the
 
1857
      log format. If the -n option is not used, ``short`` and ``line`` show
 
1858
      just the top level (mainline) while ``long`` shows all levels of merged
 
1859
      revisions.
 
1860
  
 
1861
      Status summaries are shown using status flags like A, M, etc. To see
 
1862
      the changes explained using words like ``added`` and ``modified``
 
1863
      instead, use the -vv option.
 
1864
  
 
1865
    :Ordering control:
 
1866
  
 
1867
      To display revisions from oldest to newest, use the --forward option.
 
1868
      In most cases, using this option will have little impact on the total
 
1869
      time taken to produce a log, though --forward does not incrementally
 
1870
      display revisions like --reverse does when it can.
 
1871
  
 
1872
    :Revision filtering:
 
1873
  
 
1874
      The -r option can be used to specify what revision or range of revisions
 
1875
      to filter against. The various forms are shown below::
 
1876
  
 
1877
        -rX      display revision X
 
1878
        -rX..    display revision X and later
 
1879
        -r..Y    display up to and including revision Y
 
1880
        -rX..Y   display from X to Y inclusive
 
1881
  
 
1882
      See ``bzr help revisionspec`` for details on how to specify X and Y.
 
1883
      Some common examples are given below::
 
1884
  
 
1885
        -r-1                show just the tip
 
1886
        -r-10..             show the last 10 mainline revisions
 
1887
        -rsubmit:..         show what's new on this branch
 
1888
        -rancestor:path..   show changes since the common ancestor of this
 
1889
                            branch and the one at location path
 
1890
        -rdate:yesterday..  show changes since yesterday
 
1891
  
 
1892
      When logging a range of revisions using -rX..Y, log starts at
 
1893
      revision Y and searches back in history through the primary
 
1894
      ("left-hand") parents until it finds X. When logging just the
 
1895
      top level (using -n1), an error is reported if X is not found
 
1896
      along the way. If multi-level logging is used (-n0), X may be
 
1897
      a nested merge revision and the log will be truncated accordingly.
 
1898
 
 
1899
    :Path filtering:
 
1900
  
 
1901
      If a parameter is given and it's not a branch, the log will be filtered
 
1902
      to show only those revisions that changed the nominated file or
 
1903
      directory.
 
1904
  
 
1905
      Filenames are interpreted within their historical context. To log a
 
1906
      deleted file, specify a revision range so that the file existed at
 
1907
      the end or start of the range.
 
1908
  
 
1909
      Historical context is also important when interpreting pathnames of
 
1910
      renamed files/directories. Consider the following example:
 
1911
  
 
1912
      * revision 1: add tutorial.txt
 
1913
      * revision 2: modify tutorial.txt
 
1914
      * revision 3: rename tutorial.txt to guide.txt; add tutorial.txt
 
1915
  
 
1916
      In this case:
 
1917
  
 
1918
      * ``bzr log guide.txt`` will log the file added in revision 1
 
1919
  
 
1920
      * ``bzr log tutorial.txt`` will log the new file added in revision 3
 
1921
  
 
1922
      * ``bzr log -r2 -p tutorial.txt`` will show the changes made to
 
1923
        the original file in revision 2.
 
1924
  
 
1925
      * ``bzr log -r2 -p guide.txt`` will display an error message as there
 
1926
        was no file called guide.txt in revision 2.
 
1927
  
 
1928
      Renames are always followed by log. By design, there is no need to
 
1929
      explicitly ask for this (and no way to stop logging a file back
 
1930
      until it was last renamed).
 
1931
  
 
1932
      Note: If the path is a directory, only revisions that directly changed
 
1933
      that directory object are currently shown. This is considered a bug.
 
1934
      (Support for filtering against multiple files and for files within a
 
1935
      directory is under development.)
 
1936
  
 
1937
    :Other filtering:
 
1938
  
 
1939
      The --message option can be used for finding revisions that match a
 
1940
      regular expression in a commit message.
 
1941
  
 
1942
    :Tips & tricks:
 
1943
  
 
1944
      GUI tools and IDEs are often better at exploring history than command
 
1945
      line tools. You may prefer qlog or glog from the QBzr and Bzr-Gtk packages
 
1946
      respectively for example. (TortoiseBzr uses qlog for displaying logs.) See
 
1947
      http://bazaar-vcs.org/BzrPlugins and http://bazaar-vcs.org/IDEIntegration.
 
1948
  
 
1949
      Web interfaces are often better at exploring history than command line
 
1950
      tools, particularly for branches on servers. You may prefer Loggerhead
 
1951
      or one of its alternatives. See http://bazaar-vcs.org/WebInterface.
 
1952
  
 
1953
      You may find it useful to add the aliases below to ``bazaar.conf``::
 
1954
  
 
1955
        [ALIASES]
 
1956
        tip = log -r-1 -n1
 
1957
        top = log -r-10.. --short --forward
 
1958
        show = log -v -p -n1 --long
 
1959
  
 
1960
      ``bzr tip`` will then show the latest revision while ``bzr top``
 
1961
      will show the last 10 mainline revisions. To see the details of a
 
1962
      particular revision X,  ``bzr show -rX``.
 
1963
  
 
1964
      As many GUI tools and Web interfaces do, you may prefer viewing
 
1965
      history collapsed initially. If you are interested in looking deeper
 
1966
      into a particular merge X, use ``bzr log -n0 -rX``. If you like
 
1967
      working this way, you may wish to either:
 
1968
  
 
1969
      * change your default log format to short (or line)
 
1970
      * add this alias: log = log -n1
 
1971
  
 
1972
      ``bzr log -v`` on a branch with lots of history is currently
 
1973
      very slow. A fix for this issue is currently under development.
 
1974
      With or without that fix, it is recommended that a revision range
 
1975
      be given when using the -v option.
 
1976
  
 
1977
      bzr has a generic full-text matching plugin, bzr-search, that can be
 
1978
      used to find revisions matching user names, commit messages, etc.
 
1979
      Among other features, this plugin can find all revisions containing
 
1980
      a list of words but not others.
 
1981
  
 
1982
      When exploring non-mainline history on large projects with deep
 
1983
      history, the performance of log can be greatly improved by installing
 
1984
      the revnocache plugin. This plugin buffers historical information
 
1985
      trading disk space for faster speed.
1842
1986
    """
1843
 
 
1844
 
    # TODO: Make --revision support uuid: and hash: [future tag:] notation.
1845
 
 
1846
1987
    takes_args = ['location?']
 
1988
    _see_also = ['log-formats', 'revisionspec']
1847
1989
    takes_options = [
1848
1990
            Option('forward',
1849
1991
                   help='Show from oldest to newest.'),