annotate en/daily.tex @ 292:f72e4be6dd37

intermediate commit.
author Yoshiki Yazawa <yaz@cc.rim.or.jp>
date Thu, 07 Feb 2008 18:56:42 +0900
parents 00f69e8825c5
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
1 \chapter{Mercurial in daily use}
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
2 \label{chap:daily}
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
3
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
4 \section{Telling Mercurial which files to track}
42
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
5
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
6 Mercurial does not work with files in your repository unless you tell
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
7 it to manage them. The \hgcmd{status} command will tell you which
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
8 files Mercurial doesn't know about; it uses a ``\texttt{?}'' to
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
9 display such files.
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
10
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
11 To tell Mercurial to track a file, use the \hgcmd{add} command. Once
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
12 you have added a file, the entry in the output of \hgcmd{status} for
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
13 that file changes from ``\texttt{?}'' to ``\texttt{A}''.
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
14 \interaction{daily.files.add}
42
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
15
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
16 After you run a \hgcmd{commit}, the files that you added before the
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
17 commit will no longer be listed in the output of \hgcmd{status}. The
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
18 reason for this is that \hgcmd{status} only tells you about
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
19 ``interesting'' files---those that you have modified or told Mercurial
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
20 to do something with---by default. If you have a repository that
42
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
21 contains thousands of files, you will rarely want to know about files
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
22 that Mercurial is tracking, but that have not changed. (You can still
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
23 get this information; we'll return to this later.)
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
24
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
25 Once you add a file, Mercurial doesn't do anything with it
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
26 immediately. Instead, it will take a snapshot of the file's state the
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
27 next time you perform a commit. It will then continue to track the
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
28 changes you make to the file every time you commit, until you remove
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
29 the file.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
30
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
31 \subsection{Explicit versus implicit file naming}
42
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
32
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
33 A useful behaviour that Mercurial has is that if you pass the name of
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
34 a directory to a command, every Mercurial command will treat this as
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
35 ``I want to operate on every file in this directory and its
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
36 subdirectories''.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
37 \interaction{daily.files.add-dir}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
38 Notice in this example that Mercurial printed the names of the files
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
39 it added, whereas it didn't do so when we added the file named
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
40 \filename{a} in the earlier example.
42
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
41
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
42 What's going on is that in the former case, we explicitly named the
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
43 file to add on the command line, so the assumption that Mercurial
178
1b55292716a4 correct single typo in chpt 5 text
Steve Guidon <steve.guidon@gmail.com>
parents: 156
diff changeset
44 makes in such cases is that you know what you were doing, and it
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
45 doesn't print any output.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
46
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
47 However, when we \emph{imply} the names of files by giving the name of
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
48 a directory, Mercurial takes the extra step of printing the name of
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
49 each file that it does something with. This makes it more clear what
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
50 is happening, and reduces the likelihood of a silent and nasty
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
51 surprise. This behaviour is common to most Mercurial commands.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
52
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
53 \subsection{Aside: Mercurial tracks files, not directories}
42
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
54
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
55 Mercurial does not track directory information. Instead, it tracks
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
56 the path to a file. Before creating a file, it first creates any
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
57 missing directory components of the path. After it deletes a file, it
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
58 then deletes any empty directories that were in the deleted file's
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
59 path. This sounds like a trivial distinction, but it has one minor
42
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
60 practical consequence: it is not possible to represent a completely
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
61 empty directory in Mercurial.
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
62
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
63 Empty directories are rarely useful, and there are unintrusive
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
64 workarounds that you can use to achieve an appropriate effect. The
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
65 developers of Mercurial thus felt that the complexity that would be
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
66 required to manage empty directories was not worth the limited benefit
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
67 this feature would bring.
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
68
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
69 If you need an empty directory in your repository, there are a few
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
70 ways to achieve this. One is to create a directory, then \hgcmd{add} a
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
71 ``hidden'' file to that directory. On Unix-like systems, any file
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
72 name that begins with a period (``\texttt{.}'') is treated as hidden
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
73 by most commands and GUI tools. This approach is illustrated in
43
7ac85766db0f Rename, remove.
Bryan O'Sullivan <bos@serpentine.com>
parents: 42
diff changeset
74 figure~\ref{ex:daily:hidden}.
42
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
75
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
76 \begin{figure}[ht]
43
7ac85766db0f Rename, remove.
Bryan O'Sullivan <bos@serpentine.com>
parents: 42
diff changeset
77 \interaction{daily.files.hidden}
7ac85766db0f Rename, remove.
Bryan O'Sullivan <bos@serpentine.com>
parents: 42
diff changeset
78 \caption{Simulating an empty directory using a hidden file}
7ac85766db0f Rename, remove.
Bryan O'Sullivan <bos@serpentine.com>
parents: 42
diff changeset
79 \label{ex:daily:hidden}
42
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
80 \end{figure}
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
81
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
82 Another way to tackle a need for an empty directory is to simply
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
83 create one in your automated build scripts before they will need it.
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
84
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
85 \section{How to stop tracking a file}
42
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
86
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
87 Once you decide that a file no longer belongs in your repository, use
42
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
88 the \hgcmd{remove} command; this deletes the file, and tells Mercurial
43
7ac85766db0f Rename, remove.
Bryan O'Sullivan <bos@serpentine.com>
parents: 42
diff changeset
89 to stop tracking it. A removed file is represented in the output of
7ac85766db0f Rename, remove.
Bryan O'Sullivan <bos@serpentine.com>
parents: 42
diff changeset
90 \hgcmd{status} with a ``\texttt{R}''.
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
91 \interaction{daily.files.remove}
42
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
92
118
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
93 After you \hgcmd{remove} a file, Mercurial will no longer track
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
94 changes to that file, even if you recreate a file with the same name
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
95 in your working directory. If you do recreate a file with the same
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
96 name and want Mercurial to track the new file, simply \hgcmd{add} it.
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
97 Mercurial will know that the newly added file is not related to the
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
98 old file of the same name.
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
99
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
100 \subsection{Removing a file does not affect its history}
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
101
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
102 It is important to understand that removing a file has only two
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
103 effects.
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
104 \begin{itemize}
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
105 \item It removes the current version of the file from the working
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
106 directory.
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
107 \item It stops Mercurial from tracking changes to the file, from the
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
108 time of the next commit.
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
109 \end{itemize}
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
110 Removing a file \emph{does not} in any way alter the \emph{history} of
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
111 the file.
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
112
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
113 If you update the working directory to a changeset in which a file
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
114 that you have removed was still tracked, it will reappear in the
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
115 working directory, with the contents it had when you committed that
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
116 changeset. If you then update the working directory to a later
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
117 changeset, in which the file had been removed, Mercurial will once
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
118 again remove the file from the working directory.
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
119
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
120 \subsection{Missing files}
42
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
121
43
7ac85766db0f Rename, remove.
Bryan O'Sullivan <bos@serpentine.com>
parents: 42
diff changeset
122 Mercurial considers a file that you have deleted, but not used
7ac85766db0f Rename, remove.
Bryan O'Sullivan <bos@serpentine.com>
parents: 42
diff changeset
123 \hgcmd{remove} to delete, to be \emph{missing}. A missing file is
7ac85766db0f Rename, remove.
Bryan O'Sullivan <bos@serpentine.com>
parents: 42
diff changeset
124 represented with ``\texttt{!}'' in the output of \hgcmd{status}.
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
125 Mercurial commands will not generally do anything with missing files.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
126 \interaction{daily.files.missing}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
127
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
128 If your repository contains a file that \hgcmd{status} reports as
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
129 missing, and you want the file to stay gone, you can run
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
130 \hgcmdargs{remove}{\hgopt{remove}{--after}} at any time later on, to
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
131 tell Mercurial that you really did mean to remove the file.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
132 \interaction{daily.files.remove-after}
43
7ac85766db0f Rename, remove.
Bryan O'Sullivan <bos@serpentine.com>
parents: 42
diff changeset
133
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
134 On the other hand, if you deleted the missing file by accident, use
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
135 \hgcmdargs{revert}{\emph{filename}} to recover the file. It will
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
136 reappear, in unmodified form.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
137 \interaction{daily.files.recover-missing}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
138
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
139 \subsection{Aside: why tell Mercurial explicitly to
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
140 remove a file?}
42
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
141
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
142 You might wonder why Mercurial requires you to explicitly tell it that
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
143 you are deleting a file. Early during the development of Mercurial,
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
144 it let you delete a file however you pleased; Mercurial would notice
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
145 the absence of the file automatically when you next ran a
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
146 \hgcmd{commit}, and stop tracking the file. In practice, this made it
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
147 too easy to accidentally remove a file without noticing.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
148
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
149 \subsection{Useful shorthand---adding and removing files
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
150 in one step}
42
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
151
43
7ac85766db0f Rename, remove.
Bryan O'Sullivan <bos@serpentine.com>
parents: 42
diff changeset
152 Mercurial offers a combination command, \hgcmd{addremove}, that adds
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
153 untracked files and marks missing files as removed.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
154 \interaction{daily.files.addremove}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
155 The \hgcmd{commit} command also provides a \hgopt{commit}{-A} option
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
156 that performs this same add-and-remove, immediately followed by a
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
157 commit.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
158 \interaction{daily.files.commit-addremove}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
159
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
160 \section{Copying files}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
161
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
162 Mercurial provides a \hgcmd{copy} command that lets you make a new
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
163 copy of a file. When you copy a file using this command, Mercurial
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
164 makes a record of the fact that the new file is a copy of the original
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
165 file. It treats these copied files specially when you merge your work
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
166 with someone else's.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
167
121
9094c9fda8ec Start chapter on error recovery.
Bryan O'Sullivan <bos@serpentine.com>
parents: 118
diff changeset
168 \subsection{The results of copying during a merge}
9094c9fda8ec Start chapter on error recovery.
Bryan O'Sullivan <bos@serpentine.com>
parents: 118
diff changeset
169
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
170 What happens during a merge is that changes ``follow'' a copy. To
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
171 best illustrate what this means, let's create an example. We'll start
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
172 with the usual tiny repository that contains a single file.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
173 \interaction{daily.copy.init}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
174 We need to do some work in parallel, so that we'll have something to
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
175 merge. So let's clone our repository.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
176 \interaction{daily.copy.clone}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
177 Back in our initial repository, let's use the \hgcmd{copy} command to
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
178 make a copy of the first file we created.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
179 \interaction{daily.copy.copy}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
180
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
181 If we look at the output of the \hgcmd{status} command afterwards, the
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
182 copied file looks just like a normal added file.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
183 \interaction{daily.copy.status}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
184 But if we pass the \hgopt{status}{-C} option to \hgcmd{status}, it
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
185 prints another line of output: this is the file that our newly-added
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
186 file was copied \emph{from}.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
187 \interaction{daily.copy.status-copy}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
188
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
189 Now, back in the repository we cloned, let's make a change in
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
190 parallel. We'll add a line of content to the original file that we
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
191 created.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
192 \interaction{daily.copy.other}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
193 Now we have a modified \filename{file} in this repository. When we
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
194 pull the changes from the first repository, and merge the two heads,
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
195 Mercurial will propagate the changes that we made locally to
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
196 \filename{file} into its copy, \filename{new-file}.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
197 \interaction{daily.copy.merge}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
198
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
199 \subsection{Why should changes follow copies?}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
200 \label{sec:daily:why-copy}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
201
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
202 This behaviour, of changes to a file propagating out to copies of the
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
203 file, might seem esoteric, but in most cases it's highly desirable.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
204
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
205 First of all, remember that this propagation \emph{only} happens when
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
206 you merge. So if you \hgcmd{copy} a file, and subsequently modify the
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
207 original file during the normal course of your work, nothing will
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
208 happen.
42
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
209
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
210 The second thing to know is that modifications will only propagate
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
211 across a copy as long as the repository that you're pulling changes
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
212 from \emph{doesn't know} about the copy.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
213
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
214 The reason that Mercurial does this is as follows. Let's say I make
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
215 an important bug fix in a source file, and commit my changes.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
216 Meanwhile, you've decided to \hgcmd{copy} the file in your repository,
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
217 without knowing about the bug or having seen the fix, and you have
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
218 started hacking on your copy of the file.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
219
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
220 If you pulled and merged my changes, and Mercurial \emph{didn't}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
221 propagate changes across copies, your source file would now contain
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
222 the bug, and unless you remembered to propagate the bug fix by hand,
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
223 the bug would \emph{remain} in your copy of the file.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
224
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
225 By automatically propagating the change that fixed the bug from the
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
226 original file to the copy, Mercurial prevents this class of problem.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
227 To my knowledge, Mercurial is the \emph{only} revision control system
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
228 that propagates changes across copies like this.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
229
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
230 Once your change history has a record that the copy and subsequent
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
231 merge occurred, there's usually no further need to propagate changes
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
232 from the original file to the copied file, and that's why Mercurial
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
233 only propagates changes across copies until this point, and no
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
234 further.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
235
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
236 \subsection{How to make changes \emph{not} follow a copy}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
237
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
238 If, for some reason, you decide that this business of automatically
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
239 propagating changes across copies is not for you, simply use your
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
240 system's normal file copy command (on Unix-like systems, that's
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
241 \command{cp}) to make a copy of a file, then \hgcmd{add} the new copy
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
242 by hand. Before you do so, though, please do reread
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
243 section~\ref{sec:daily:why-copy}, and make an informed decision that
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
244 this behaviour is not appropriate to your specific case.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
245
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
246 \subsection{Behaviour of the \hgcmd{copy} command}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
247
118
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
248 When you use the \hgcmd{copy} command, Mercurial makes a copy of each
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
249 source file as it currently stands in the working directory. This
181
d4570b8c78bd Be more explicit about the behaviour of copy with modified files.
Bryan O'Sullivan <bos@serpentine.com>
parents: 180
diff changeset
250 means that if you make some modifications to a file, then \hgcmd{copy}
d4570b8c78bd Be more explicit about the behaviour of copy with modified files.
Bryan O'Sullivan <bos@serpentine.com>
parents: 180
diff changeset
251 it without first having committed those changes, the new copy will
d4570b8c78bd Be more explicit about the behaviour of copy with modified files.
Bryan O'Sullivan <bos@serpentine.com>
parents: 180
diff changeset
252 also contain the modifications you have made up until that point. (I
d4570b8c78bd Be more explicit about the behaviour of copy with modified files.
Bryan O'Sullivan <bos@serpentine.com>
parents: 180
diff changeset
253 find this behaviour a little counterintuitive, which is why I mention
d4570b8c78bd Be more explicit about the behaviour of copy with modified files.
Bryan O'Sullivan <bos@serpentine.com>
parents: 180
diff changeset
254 it here.)
118
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
255
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
256 The \hgcmd{copy} command acts similarly to the Unix \command{cp}
118
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
257 command (you can use the \hgcmd{cp} alias if you prefer). The last
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
258 argument is the \emph{destination}, and all prior arguments are
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
259 \emph{sources}. If you pass it a single file as the source, and the
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
260 destination does not exist, it creates a new file with that name.
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
261 \interaction{daily.copy.simple}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
262 If the destination is a directory, Mercurial copies its sources into
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
263 that directory.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
264 \interaction{daily.copy.dir-dest}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
265 Copying a directory is recursive, and preserves the directory
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
266 structure of the source.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
267 \interaction{daily.copy.dir-src}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
268 If the source and destination are both directories, the source tree is
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
269 recreated in the destination directory.
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
270 \interaction{daily.copy.dir-src-dest}
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
271
118
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
272 As with the \hgcmd{rename} command, if you copy a file manually and
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
273 then want Mercurial to know that you've copied the file, simply use
236
abebe72451d6 Fix thinko.
Bryan O'Sullivan <bos@serpentine.com>
parents: 182
diff changeset
274 the \hgopt{copy}{--after} option to \hgcmd{copy}.
118
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
275 \interaction{daily.copy.after}
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
276
117
6b0f4498569e Beef up daily routine material. Focus on merge-across-copy.
Bryan O'Sullivan <bos@serpentine.com>
parents: 43
diff changeset
277 \section{Renaming files}
43
7ac85766db0f Rename, remove.
Bryan O'Sullivan <bos@serpentine.com>
parents: 42
diff changeset
278
118
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
279 It's rather more common to need to rename a file than to make a copy
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
280 of it. The reason I discussed the \hgcmd{copy} command before talking
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
281 about renaming files is that Mercurial treats a rename in essentially
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
282 the same way as a copy. Therefore, knowing what Mercurial does when
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
283 you copy a file tells you what to expect when you rename a file.
43
7ac85766db0f Rename, remove.
Bryan O'Sullivan <bos@serpentine.com>
parents: 42
diff changeset
284
118
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
285 When you use the \hgcmd{rename} command, Mercurial makes a copy of
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
286 each source file, then deletes it and marks the file as removed.
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
287 \interaction{daily.rename.rename}
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
288 The \hgcmd{status} command shows the newly copied file as added, and
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
289 the copied-from file as removed.
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
290 \interaction{daily.rename.status}
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
291 As with the results of a \hgcmd{copy}, we must use the
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
292 \hgopt{status}{-C} option to \hgcmd{status} to see that the added file
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
293 is really being tracked by Mercurial as a copy of the original, now
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
294 removed, file.
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
295 \interaction{daily.rename.status-copy}
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
296
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
297 As with \hgcmd{remove} and \hgcmd{copy}, you can tell Mercurial about
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
298 a rename after the fact using the \hgopt{rename}{--after} option. In
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
299 most other respects, the behaviour of the \hgcmd{rename} command, and
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
300 the options it accepts, are similar to the \hgcmd{copy} command.
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
301
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
302 \subsection{Renaming files and merging changes}
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
303
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
304 Since Mercurial's rename is implemented as copy-and-remove, the same
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
305 propagation of changes happens when you merge after a rename as after
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
306 a copy.
1ee53cb37a99 More progress on daily work.
Bryan O'Sullivan <bos@serpentine.com>
parents: 117
diff changeset
307
156
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
308 If I modify a file, and you rename it to a new name, and then we merge
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
309 our respective changes, my modifications to the file under its
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
310 original name will be propagated into the file under its new name.
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
311 (This is something you might expect to ``simply work,'' but not all
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
312 revision control systems actually do this.)
43
7ac85766db0f Rename, remove.
Bryan O'Sullivan <bos@serpentine.com>
parents: 42
diff changeset
313
121
9094c9fda8ec Start chapter on error recovery.
Bryan O'Sullivan <bos@serpentine.com>
parents: 118
diff changeset
314 Whereas having changes follow a copy is a feature where you can
9094c9fda8ec Start chapter on error recovery.
Bryan O'Sullivan <bos@serpentine.com>
parents: 118
diff changeset
315 perhaps nod and say ``yes, that might be useful,'' it should be clear
9094c9fda8ec Start chapter on error recovery.
Bryan O'Sullivan <bos@serpentine.com>
parents: 118
diff changeset
316 that having them follow a rename is definitely important. Without
9094c9fda8ec Start chapter on error recovery.
Bryan O'Sullivan <bos@serpentine.com>
parents: 118
diff changeset
317 this facility, it would simply be too easy for changes to become
9094c9fda8ec Start chapter on error recovery.
Bryan O'Sullivan <bos@serpentine.com>
parents: 118
diff changeset
318 orphaned when files are renamed.
9094c9fda8ec Start chapter on error recovery.
Bryan O'Sullivan <bos@serpentine.com>
parents: 118
diff changeset
319
156
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
320 \subsection{Divergent renames and merging}
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
321
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
322 The case of diverging names occurs when two developers start with a
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
323 file---let's call it \filename{foo}---in their respective
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
324 repositories.
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
325
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
326 \interaction{rename.divergent.clone}
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
327 Anne renames the file to \filename{bar}.
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
328 \interaction{rename.divergent.rename.anne}
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
329 Meanwhile, Bob renames it to \filename{quux}.
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
330 \interaction{rename.divergent.rename.bob}
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
331
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
332 I like to think of this as a conflict because each developer has
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
333 expressed different intentions about what the file ought to be named.
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
334
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
335 What do you think should happen when they merge their work?
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
336 Mercurial's actual behaviour is that it always preserves \emph{both}
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
337 names when it merges changesets that contain divergent renames.
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
338 \interaction{rename.divergent.merge}
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
339
273
00f69e8825c5 Bring book up to date with recent changes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 236
diff changeset
340 Notice that Mercurial does warn about the divergent renames, but it
00f69e8825c5 Bring book up to date with recent changes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 236
diff changeset
341 leaves it up to you to do something about the divergence after the merge.
156
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
342
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
343 \subsection{Convergent renames and merging}
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
344
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
345 Another kind of rename conflict occurs when two people choose to
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
346 rename different \emph{source} files to the same \emph{destination}.
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
347 In this case, Mercurial runs its normal merge machinery, and lets you
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
348 guide it to a suitable resolution.
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
349
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
350 \subsection{Other name-related corner cases}
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
351
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
352 Mercurial has a longstanding bug in which it fails to handle a merge
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
353 where one side has a file with a given name, while another has a
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
354 directory with the same name. This is documented as~\bug{29}.
91a936be78b8 Document merge behaviour with file names.
Bryan O'Sullivan <bos@serpentine.com>
parents: 121
diff changeset
355 \interaction{issue29.go}
121
9094c9fda8ec Start chapter on error recovery.
Bryan O'Sullivan <bos@serpentine.com>
parents: 118
diff changeset
356
180
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
357 \section{Recovering from mistakes}
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
358
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
359 Mercurial has some useful commands that will help you to recover from
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
360 some common mistakes.
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
361
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
362 The \hgcmd{revert} command lets you undo changes that you have made to
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
363 your working directory. For example, if you \hgcmd{add} a file by
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
364 accident, just run \hgcmd{revert} with the name of the file you added,
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
365 and while the file won't be touched in any way, it won't be tracked
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
366 for adding by Mercurial any longer, either. You can also use
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
367 \hgcmd{revert} to get rid of erroneous changes to a file.
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
368
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
369 It's useful to remember that the \hgcmd{revert} command is useful for
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
370 changes that you have not yet committed. Once you've committed a
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
371 change, if you decide it was a mistake, you can still do something
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
372 about it, though your options may be more limited.
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
373
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
374 For more information about the \hgcmd{revert} command, and details
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
375 about how to deal with changes you have already committed, see
182
c005d0181c0b Fix typo in reference.
Bryan O'Sullivan <bos@serpentine.com>
parents: 181
diff changeset
376 chapter~\ref{chap:undo}.
180
6413f88338df Point to chapter on undoing mistakes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 178
diff changeset
377
42
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
378 %%% Local Variables:
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
379 %%% mode: latex
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
380 %%% TeX-master: "00book"
cbfa08bcf181 Start the "Mercurial in daily use" chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
381 %%% End: