← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/builtins.py

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2009-05-13 05:39:11 UTC
  • mfrom: (4353.1.1 integration)
  • Revision ID: pqm@pqm.ubuntu.com-20090513053911-fjajgycew5in8q5s
(igc) improve commit help and error message (Ian Clatworthy)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/builtins.py
2727
2727
class cmd_commit(Command):
2728
2728
    """Commit changes into a new revision.
2729
2729
 
2730
 
    If no arguments are given, the entire tree is committed.
2731
 
 
2732
 
    If selected files are specified, only changes to those files are
2733
 
    committed.  If a directory is specified then the directory and everything
2734
 
    within it is committed.
2735
 
 
2736
 
    When excludes are given, they take precedence over selected files.
2737
 
    For example, too commit only changes within foo, but not changes within
2738
 
    foo/bar::
2739
 
 
2740
 
      bzr commit foo -x foo/bar
2741
 
 
2742
 
    If author of the change is not the same person as the committer, you can
2743
 
    specify the author's name using the --author option. The name should be
2744
 
    in the same format as a committer-id, e.g. "John Doe <jdoe@example.com>".
2745
 
    If there is more than one author of the change you can specify the option
2746
 
    multiple times, once for each author.
2747
 
 
2748
 
    A selected-file commit may fail in some cases where the committed
2749
 
    tree would be invalid. Consider::
2750
 
 
2751
 
      bzr init foo
2752
 
      mkdir foo/bar
2753
 
      bzr add foo/bar
2754
 
      bzr commit foo -m "committing foo"
2755
 
      bzr mv foo/bar foo/baz
2756
 
      mkdir foo/bar
2757
 
      bzr add foo/bar
2758
 
      bzr commit foo/bar -m "committing bar but not baz"
2759
 
 
2760
 
    In the example above, the last commit will fail by design. This gives
2761
 
    the user the opportunity to decide whether they want to commit the
2762
 
    rename at the same time, separately first, or not at all. (As a general
2763
 
    rule, when in doubt, Bazaar has a policy of Doing the Safe Thing.)
2764
 
 
2765
 
    Note: A selected-file commit after a merge is not yet supported.
 
2730
    An explanatory message needs to be given for each commit. This is
 
2731
    often done by using the --message option (getting the message from the
 
2732
    command line) or by using the --file option (getting the message from
 
2733
    a file). If neither of these options is given, an editor is opened for
 
2734
    the user to enter the message. To see the changed files in the
 
2735
    boilerplate text loaded into the editor, use the --show-diff option.
 
2736
 
 
2737
    By default, the entire tree is committed and the person doing the
 
2738
    commit is assumed to be the author. These defaults can be overridden
 
2739
    as explained below.
 
2740
 
 
2741
    :Selective commits:
 
2742
 
 
2743
      If selected files are specified, only changes to those files are
 
2744
      committed.  If a directory is specified then the directory and
 
2745
      everything within it is committed.
 
2746
  
 
2747
      When excludes are given, they take precedence over selected files.
 
2748
      For example, to commit only changes within foo, but not changes
 
2749
      within foo/bar::
 
2750
  
 
2751
        bzr commit foo -x foo/bar
 
2752
  
 
2753
      A selective commit after a merge is not yet supported.
 
2754
 
 
2755
    :Custom authors:
 
2756
 
 
2757
      If the author of the change is not the same person as the committer,
 
2758
      you can specify the author's name using the --author option. The
 
2759
      name should be in the same format as a committer-id, e.g.
 
2760
      "John Doe <jdoe@example.com>". If there is more than one author of
 
2761
      the change you can specify the option multiple times, once for each
 
2762
      author.
 
2763
  
 
2764
    :Checks:
 
2765
 
 
2766
      A common mistake is to forget to add a new file or directory before
 
2767
      running the commit command. The --strict option checks for unknown
 
2768
      files and aborts the commit if any are found. More advanced pre-commit
 
2769
      checks can be implemented by defining hooks. See ``bzr help hooks``
 
2770
      for details.
 
2771
 
 
2772
    :Things to note:
 
2773
 
 
2774
      If you accidentially commit the wrong changes or make a spelling
 
2775
      mistake in the commit message say, you can use the uncommit command
 
2776
      to undo it. See ``bzr help uncommit`` for details.
 
2777
 
 
2778
      Hooks can also be configured to run after a commit. This allows you
 
2779
      to trigger updates to external systems like bug trackers. The --fixes
 
2780
      option can be used to record the association between a revision and
 
2781
      one or more bugs. See ``bzr help bugs`` for details.
 
2782
 
 
2783
      A selective commit may fail in some cases where the committed
 
2784
      tree would be invalid. Consider::
 
2785
  
 
2786
        bzr init foo
 
2787
        mkdir foo/bar
 
2788
        bzr add foo/bar
 
2789
        bzr commit foo -m "committing foo"
 
2790
        bzr mv foo/bar foo/baz
 
2791
        mkdir foo/bar
 
2792
        bzr add foo/bar
 
2793
        bzr commit foo/bar -m "committing bar but not baz"
 
2794
  
 
2795
      In the example above, the last commit will fail by design. This gives
 
2796
      the user the opportunity to decide whether they want to commit the
 
2797
      rename at the same time, separately first, or not at all. (As a general
 
2798
      rule, when in doubt, Bazaar has a policy of Doing the Safe Thing.)
2766
2799
    """
2767
2800
    # TODO: Run hooks on tree to-be-committed, and after commit.
2768
2801
 
2773
2806
 
2774
2807
    # XXX: verbose currently does nothing
2775
2808
 
2776
 
    _see_also = ['bugs', 'uncommit']
 
2809
    _see_also = ['add', 'bugs', 'hooks', 'uncommit']
2777
2810
    takes_args = ['selected*']
2778
2811
    takes_options = [
2779
2812
            ListOption('exclude', type=str, short_name='x',
2900
2933
        except PointlessCommit:
2901
2934
            # FIXME: This should really happen before the file is read in;
2902
2935
            # perhaps prepare the commit; get the message; then actually commit
2903
 
            raise errors.BzrCommandError("no changes to commit."
2904
 
                              " use --unchanged to commit anyhow")
 
2936
            raise errors.BzrCommandError("No changes to commit."
 
2937
                              " Use --unchanged to commit anyhow.")
2905
2938
        except ConflictsInTree:
2906
2939
            raise errors.BzrCommandError('Conflicts detected in working '
2907
2940
                'tree.  Use "bzr conflicts" to list, "bzr resolve FILE" to'