← 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

Turn completion assertions into separate methods.

Many common assertions used to be expressed as arguments to the complete
method.  This makes the checks more explicit, and the code easier to read.

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 accidentally 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 accidentally 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 delete 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, but deregistered)
39
 
 
40
 
On the other hand, the unchanged ``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
101
 
`Merging changes <merging_changes.html>`_ in the next chapter and the
102
 
Bazaar User Reference.
103
 
 
104
 
Undoing multiple commits
105
 
------------------------
106
 
 
107
 
You can use the -r option to undo several commits like this::
108
 
 
109
 
  bzr uncommit -r -3
110
 
 
111
 
If your reason for doing this is that you really want to
112
 
back out several changes, then be sure to remember that ``uncommit``
113
 
does not change your working tree: you'll probably need to run the
114
 
``revert`` command as well to complete the task. In many cases though,
115
 
it's arguably better to leave your history alone and add a new
116
 
revision reflecting the content of the last good state.
117
 
 
118
 
Reverting to the state of an earlier version
119
 
--------------------------------------------
120
 
 
121
 
If you make an unwanted change but it doesn't make sense to uncommit
122
 
it (because that code has been released to users say), you can use
123
 
``revert`` to take your working tree back to the desired state.
124
 
For example::
125
 
 
126
 
  % bzr commit "Fix bug #5"
127
 
  Committed revision 20.
128
 
  (release the code)
129
 
  (hmm - bad fix)
130
 
  bzr revert -r 19
131
 
  bzr commit -m "Backout fix for bug #5"
132
 
 
133
 
This will change your entire tree back to the state as of revision 19,
134
 
which is probably only what you want if you haven't made any new commits
135
 
since then. If you have, the ``revert`` would wipe them out as well. In that
136
 
case, you probably want to use `Reverse cherrypicking
137
 
<adv_merging.html#reverse-cherrypicking>`_ instead to
138
 
back out the bad fix.
139
 
 
140
 
Note: As an alternative to using an absolute revision number (like 19), you can
141
 
specify one relative to the tip (-1) using a negative number like this::
142
 
 
143
 
  bzr revert -r -2
144
 
 
145
 
Correcting a tag
146
 
----------------
147
 
 
148
 
If you have defined a tag prematurely, use the ``--force`` option of
149
 
the ``tag`` command to redefine it. For example::
150
 
 
151
 
  bzr tag 2.0-beta-1
152
 
  (oops, we're not yet ready for that)
153
 
  (make more commits to include more fixes)
154
 
  bzr tag 2.0-beta-1 --force
155
 
 
156
 
Clearing a tag
157
 
--------------
158
 
 
159
 
If you have defined a tag and no longer want it defined, use the
160
 
``--delete`` option of the ``tag`` command to remove it. For example::
161
 
 
162
 
  bzr tag 2.0-beta-4
163
 
  (oops, we're not releasing a 4th beta)
164
 
  bzr tag 2.0-beta-4 --delete
165