← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/user-guide/undoing_mistakes.txt

  • Committer: Aaron Bentley
  • Date: 2008-03-11 14:29:08 UTC
  • mto: This revision was merged to the branch mainline in revision 3264.
  • Revision ID: aaron@aaronbentley.com-20080311142908-yyrvcpn2mldt0fnn
Update documentation to reflect conflict-handling difference

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/undoing_mistakes.txt
 
1
Undoing mistakes
 
2
================
 
3
 
 
4
Mistakes happen
 
5
---------------
 
6
 
 
7
Bazaar has been designed to make it easy to
 
8
recover from mistakes as explained below.
 
9
 
 
10
Dropping the revision history for a project
 
11
-------------------------------------------
 
12
 
 
13
If you accidently put the wrong tree under version control, simply
 
14
delete the ``.bzr`` directory.
 
15
 
 
16
Deregistering a file or directory
 
17
---------------------------------
 
18
 
 
19
If you accidently register a file using ``add`` that you
 
20
don't want version controlled, you can use the ``remove``
 
21
command to tell Bazaar to forget about it.
 
22
 
 
23
``remove`` has been designed to *Do the Safe Thing* in
 
24
that it will not delete a modified file. For example::
 
25
 
 
26
  bzr add foo.html
 
27
  (oops - didn't mean that)
 
28
  bzr remove foo.html
 
29
 
 
30
This will complain about the file being modified or unknown.
 
31
If you want to keep the file, use the ``--keep`` option.
 
32
Alternatively, if you want to remove the file, use the ``--force`` option.
 
33
For example::
 
34
 
 
35
  bzr add foo.html
 
36
  (oops - didn't mean that)
 
37
  bzr remove --keep foo.html
 
38
  (foo.html left on disk)
 
39
 
 
40
On the other hand, the ``TODO`` file is deregistered and
 
41
removed from disk without complaint in this example::
 
42
 
 
43
  bzr add TODO
 
44
  bzr commit -m "added TODO"
 
45
  (hack, hack, hack - but don't change TODO)
 
46
  bzr remove TODO
 
47
  (TODO file deleted)
 
48
 
 
49
Note: If you delete a file using your file manager, IDE or via an operating
 
50
system command, the ``commit`` command will implicitly treat it as removed.
 
51
 
 
52
Undoing changes since the last commit
 
53
-------------------------------------
 
54
 
 
55
One of the reasons for using a version control tool is that it
 
56
lets you easily checkpoint good tree states while working. If you
 
57
decide that the changes you have made since the last ``commit`` ought
 
58
to be thrown away, the command to use is ``revert`` like this::
 
59
 
 
60
  bzr revert
 
61
 
 
62
As a precaution, it is good practice to use ``bzr status`` and
 
63
``bzr diff`` first to check that everything being thrown away
 
64
really ought to be.
 
65
 
 
66
Undoing changes to a file since the last commit
 
67
-----------------------------------------------
 
68
 
 
69
If you want to undo changes to a particular file since the last commit but
 
70
keep all the other changes in the tree, pass the filename as an argument
 
71
to ``revert`` like this::
 
72
 
 
73
  bzr revert foo.py
 
74
 
 
75
Undoing the last commit
 
76
-----------------------
 
77
 
 
78
If you make a commit and really didn't mean to, use the ``uncommit`` command
 
79
to undo it like this::
 
80
 
 
81
  bzr uncommit
 
82
 
 
83
Unlike ``revert``, ``uncommit`` leaves the content of your working tree
 
84
exactly as it is. That's really handy if you make a commit and accidently
 
85
provide the wrong error message. For example::
 
86
 
 
87
  bzr commit -m "Fix bug #11"
 
88
  (damn - wrong bug number)
 
89
  bzr uncommit
 
90
  bzr commit -m "Fix bug #1"
 
91
 
 
92
Another common reason for undoing a commit is because you forgot to add
 
93
one or more files. Some users like to alias ``commit`` to ``commit --strict``
 
94
so that commits fail if unknown files are found in the tree.
 
95
 
 
96
Note: While the ``merge`` command is not introduced until the next
 
97
chapter, it is worth noting now that ``uncommit`` restores any pending
 
98
merges. (Running ``bzr status`` after ``uncommit`` will show these.)
 
99
``merge`` can also be used to effectively undo just a selected commit
 
100
earlier in history. For more information on ``merge``, see `Merging changes`_
 
101
in the next chapter and the Bazaar User Reference.
 
102
 
 
103
Undoing multiple commits
 
104
------------------------
 
105
 
 
106
You can use the -r option to undo several commits like this::
 
107
 
 
108
  bzr uncommit -r -3
 
109
 
 
110
If your reason for doing this is that you really want to
 
111
back out several changes, then be sure to remember that ``uncommit``
 
112
does not change your working tree: you'll probably need to run the
 
113
``revert`` command as well to complete the task. In many cases though,
 
114
it's arguably better to leave your history alone and add a new
 
115
revision reflecting the content of the last good state.
 
116
 
 
117
Reverting to the state of an earlier version
 
118
--------------------------------------------
 
119
 
 
120
If you make an unwanted change but it doesn't make sense to uncommit
 
121
it (because that code has been released to users say), you can use
 
122
``revert`` to take your working tree back to the desired state.
 
123
For example::
 
124
 
 
125
  % bzr commit "Fix bug #5"
 
126
  Committed revision 20.
 
127
  (release the code)
 
128
  (hmm - bad fix)
 
129
  bzr revert -r 20
 
130
  bzr commit -m "Backout fix for bug #5"
 
131
 
 
132
Correcting a tag
 
133
----------------
 
134
 
 
135
If you have defined a tag prematurely, use the ``--force`` option of
 
136
the ``tag`` command to redefine it. For example::
 
137
 
 
138
  bzr tag 2.0-beta-1
 
139
  (oops, we're not yet ready for that)
 
140
  bzr tag 2.0-beta-1 --force
 
141
 
 
142
Clearing a tag
 
143
--------------
 
144
 
 
145
If you have defined a tag and no longer want it defined, use the
 
146
``--delete`` option of the ``tag`` command to remove it. For example::
 
147
 
 
148
  bzr tag 2.0-beta-4
 
149
  (oops, we're not releasing a 4th beta)
 
150
  bzr tag 2.0-beta-4 --delete
 
151