← 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: Martin Packman
  • Date: 2011-11-24 17:01:07 UTC
  • mto: This revision was merged to the branch mainline in revision 6304.
  • Revision ID: martin.packman@canonical.com-20111124170107-b3yd5vkzdglmnjk7
Allow a bracketed suffix in option help test

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