1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/fr/daily.tex	Sun Feb 08 15:38:18 2009 +0100
     1.3 @@ -0,0 +1,381 @@
     1.4 +\chapter{Mercurial in daily use}
     1.5 +\label{chap:daily}
     1.6 +
     1.7 +\section{Telling Mercurial which files to track}
     1.8 +
     1.9 +Mercurial does not work with files in your repository unless you tell
    1.10 +it to manage them.  The \hgcmd{status} command will tell you which
    1.11 +files Mercurial doesn't know about; it uses a ``\texttt{?}'' to
    1.12 +display such files.
    1.13 +
    1.14 +To tell Mercurial to track a file, use the \hgcmd{add} command.  Once
    1.15 +you have added a file, the entry in the output of \hgcmd{status} for
    1.16 +that file changes from ``\texttt{?}'' to ``\texttt{A}''.
    1.17 +\interaction{daily.files.add}
    1.18 +
    1.19 +After you run a \hgcmd{commit}, the files that you added before the
    1.20 +commit will no longer be listed in the output of \hgcmd{status}.  The
    1.21 +reason for this is that \hgcmd{status} only tells you about
    1.22 +``interesting'' files---those that you have modified or told Mercurial
    1.23 +to do something with---by default.  If you have a repository that
    1.24 +contains thousands of files, you will rarely want to know about files
    1.25 +that Mercurial is tracking, but that have not changed.  (You can still
    1.26 +get this information; we'll return to this later.)
    1.27 +
    1.28 +Once you add a file, Mercurial doesn't do anything with it
    1.29 +immediately.  Instead, it will take a snapshot of the file's state the
    1.30 +next time you perform a commit.  It will then continue to track the
    1.31 +changes you make to the file every time you commit, until you remove
    1.32 +the file.
    1.33 +
    1.34 +\subsection{Explicit versus implicit file naming}
    1.35 +
    1.36 +A useful behaviour that Mercurial has is that if you pass the name of
    1.37 +a directory to a command, every Mercurial command will treat this as
    1.38 +``I want to operate on every file in this directory and its
    1.39 +subdirectories''.
    1.40 +\interaction{daily.files.add-dir}
    1.41 +Notice in this example that Mercurial printed the names of the files
    1.42 +it added, whereas it didn't do so when we added the file named
    1.43 +\filename{a} in the earlier example.
    1.44 +
    1.45 +What's going on is that in the former case, we explicitly named the
    1.46 +file to add on the command line, so the assumption that Mercurial
    1.47 +makes in such cases is that you know what you were doing, and it
    1.48 +doesn't print any output.
    1.49 +
    1.50 +However, when we \emph{imply} the names of files by giving the name of
    1.51 +a directory, Mercurial takes the extra step of printing the name of
    1.52 +each file that it does something with.  This makes it more clear what
    1.53 +is happening, and reduces the likelihood of a silent and nasty
    1.54 +surprise.  This behaviour is common to most Mercurial commands.
    1.55 +
    1.56 +\subsection{Aside: Mercurial tracks files, not directories}
    1.57 +
    1.58 +Mercurial does not track directory information.  Instead, it tracks
    1.59 +the path to a file.  Before creating a file, it first creates any
    1.60 +missing directory components of the path.  After it deletes a file, it
    1.61 +then deletes any empty directories that were in the deleted file's
    1.62 +path.  This sounds like a trivial distinction, but it has one minor
    1.63 +practical consequence: it is not possible to represent a completely
    1.64 +empty directory in Mercurial.
    1.65 +
    1.66 +Empty directories are rarely useful, and there are unintrusive
    1.67 +workarounds that you can use to achieve an appropriate effect.  The
    1.68 +developers of Mercurial thus felt that the complexity that would be
    1.69 +required to manage empty directories was not worth the limited benefit
    1.70 +this feature would bring.
    1.71 +
    1.72 +If you need an empty directory in your repository, there are a few
    1.73 +ways to achieve this. One is to create a directory, then \hgcmd{add} a
    1.74 +``hidden'' file to that directory.  On Unix-like systems, any file
    1.75 +name that begins with a period (``\texttt{.}'') is treated as hidden
    1.76 +by most commands and GUI tools.  This approach is illustrated in
    1.77 +figure~\ref{ex:daily:hidden}.
    1.78 +
    1.79 +\begin{figure}[ht]
    1.80 +  \interaction{daily.files.hidden}
    1.81 +  \caption{Simulating an empty directory using a hidden file}
    1.82 +  \label{ex:daily:hidden}
    1.83 +\end{figure}
    1.84 +
    1.85 +Another way to tackle a need for an empty directory is to simply
    1.86 +create one in your automated build scripts before they will need it.
    1.87 +
    1.88 +\section{How to stop tracking a file}
    1.89 +
    1.90 +Once you decide that a file no longer belongs in your repository, use
    1.91 +the \hgcmd{remove} command; this deletes the file, and tells Mercurial
    1.92 +to stop tracking it.  A removed file is represented in the output of
    1.93 +\hgcmd{status} with a ``\texttt{R}''.
    1.94 +\interaction{daily.files.remove}
    1.95 +
    1.96 +After you \hgcmd{remove} a file, Mercurial will no longer track
    1.97 +changes to that file, even if you recreate a file with the same name
    1.98 +in your working directory.  If you do recreate a file with the same
    1.99 +name and want Mercurial to track the new file, simply \hgcmd{add} it.
   1.100 +Mercurial will know that the newly added file is not related to the
   1.101 +old file of the same name.
   1.102 +
   1.103 +\subsection{Removing a file does not affect its history}
   1.104 +
   1.105 +It is important to understand that removing a file has only two
   1.106 +effects.
   1.107 +\begin{itemize}
   1.108 +\item It removes the current version of the file from the working
   1.109 +  directory.
   1.110 +\item It stops Mercurial from tracking changes to the file, from the
   1.111 +  time of the next commit.
   1.112 +\end{itemize}
   1.113 +Removing a file \emph{does not} in any way alter the \emph{history} of
   1.114 +the file.
   1.115 +
   1.116 +If you update the working directory to a changeset in which a file
   1.117 +that you have removed was still tracked, it will reappear in the
   1.118 +working directory, with the contents it had when you committed that
   1.119 +changeset.  If you then update the working directory to a later
   1.120 +changeset, in which the file had been removed, Mercurial will once
   1.121 +again remove the file from the working directory.
   1.122 +
   1.123 +\subsection{Missing files}
   1.124 +
   1.125 +Mercurial considers a file that you have deleted, but not used
   1.126 +\hgcmd{remove} to delete, to be \emph{missing}.  A missing file is
   1.127 +represented with ``\texttt{!}'' in the output of \hgcmd{status}.
   1.128 +Mercurial commands will not generally do anything with missing files.
   1.129 +\interaction{daily.files.missing}
   1.130 +
   1.131 +If your repository contains a file that \hgcmd{status} reports as
   1.132 +missing, and you want the file to stay gone, you can run
   1.133 +\hgcmdargs{remove}{\hgopt{remove}{--after}} at any time later on, to
   1.134 +tell Mercurial that you really did mean to remove the file.
   1.135 +\interaction{daily.files.remove-after}
   1.136 +
   1.137 +On the other hand, if you deleted the missing file by accident, use
   1.138 +\hgcmdargs{revert}{\emph{filename}} to recover the file.  It will
   1.139 +reappear, in unmodified form.
   1.140 +\interaction{daily.files.recover-missing}
   1.141 +
   1.142 +\subsection{Aside: why tell Mercurial explicitly to 
   1.143 +  remove a file?}
   1.144 +
   1.145 +You might wonder why Mercurial requires you to explicitly tell it that
   1.146 +you are deleting a file.  Early during the development of Mercurial,
   1.147 +it let you delete a file however you pleased; Mercurial would notice
   1.148 +the absence of the file automatically when you next ran a
   1.149 +\hgcmd{commit}, and stop tracking the file.  In practice, this made it
   1.150 +too easy to accidentally remove a file without noticing.
   1.151 +
   1.152 +\subsection{Useful shorthand---adding and removing files
   1.153 +  in one step}
   1.154 +
   1.155 +Mercurial offers a combination command, \hgcmd{addremove}, that adds
   1.156 +untracked files and marks missing files as removed.  
   1.157 +\interaction{daily.files.addremove}
   1.158 +The \hgcmd{commit} command also provides a \hgopt{commit}{-A} option
   1.159 +that performs this same add-and-remove, immediately followed by a
   1.160 +commit.
   1.161 +\interaction{daily.files.commit-addremove}
   1.162 +
   1.163 +\section{Copying files}
   1.164 +
   1.165 +Mercurial provides a \hgcmd{copy} command that lets you make a new
   1.166 +copy of a file.  When you copy a file using this command, Mercurial
   1.167 +makes a record of the fact that the new file is a copy of the original
   1.168 +file.  It treats these copied files specially when you merge your work
   1.169 +with someone else's.
   1.170 +
   1.171 +\subsection{The results of copying during a merge}
   1.172 +
   1.173 +What happens during a merge is that changes ``follow'' a copy.  To
   1.174 +best illustrate what this means, let's create an example.  We'll start
   1.175 +with the usual tiny repository that contains a single file.
   1.176 +\interaction{daily.copy.init}
   1.177 +We need to do some work in parallel, so that we'll have something to
   1.178 +merge.  So let's clone our repository.
   1.179 +\interaction{daily.copy.clone}
   1.180 +Back in our initial repository, let's use the \hgcmd{copy} command to
   1.181 +make a copy of the first file we created.
   1.182 +\interaction{daily.copy.copy}
   1.183 +
   1.184 +If we look at the output of the \hgcmd{status} command afterwards, the
   1.185 +copied file looks just like a normal added file.
   1.186 +\interaction{daily.copy.status}
   1.187 +But if we pass the \hgopt{status}{-C} option to \hgcmd{status}, it
   1.188 +prints another line of output: this is the file that our newly-added
   1.189 +file was copied \emph{from}.
   1.190 +\interaction{daily.copy.status-copy}
   1.191 +
   1.192 +Now, back in the repository we cloned, let's make a change in
   1.193 +parallel.  We'll add a line of content to the original file that we
   1.194 +created.
   1.195 +\interaction{daily.copy.other}
   1.196 +Now we have a modified \filename{file} in this repository.  When we
   1.197 +pull the changes from the first repository, and merge the two heads,
   1.198 +Mercurial will propagate the changes that we made locally to
   1.199 +\filename{file} into its copy, \filename{new-file}.
   1.200 +\interaction{daily.copy.merge}
   1.201 +
   1.202 +\subsection{Why should changes follow copies?}
   1.203 +\label{sec:daily:why-copy}
   1.204 +
   1.205 +This behaviour, of changes to a file propagating out to copies of the
   1.206 +file, might seem esoteric, but in most cases it's highly desirable.
   1.207 +
   1.208 +First of all, remember that this propagation \emph{only} happens when
   1.209 +you merge.  So if you \hgcmd{copy} a file, and subsequently modify the
   1.210 +original file during the normal course of your work, nothing will
   1.211 +happen.
   1.212 +
   1.213 +The second thing to know is that modifications will only propagate
   1.214 +across a copy as long as the repository that you're pulling changes
   1.215 +from \emph{doesn't know} about the copy.
   1.216 +
   1.217 +The reason that Mercurial does this is as follows.  Let's say I make
   1.218 +an important bug fix in a source file, and commit my changes.
   1.219 +Meanwhile, you've decided to \hgcmd{copy} the file in your repository,
   1.220 +without knowing about the bug or having seen the fix, and you have
   1.221 +started hacking on your copy of the file.
   1.222 +
   1.223 +If you pulled and merged my changes, and Mercurial \emph{didn't}
   1.224 +propagate changes across copies, your source file would now contain
   1.225 +the bug, and unless you remembered to propagate the bug fix by hand,
   1.226 +the bug would \emph{remain} in your copy of the file.
   1.227 +
   1.228 +By automatically propagating the change that fixed the bug from the
   1.229 +original file to the copy, Mercurial prevents this class of problem.
   1.230 +To my knowledge, Mercurial is the \emph{only} revision control system
   1.231 +that propagates changes across copies like this.
   1.232 +
   1.233 +Once your change history has a record that the copy and subsequent
   1.234 +merge occurred, there's usually no further need to propagate changes
   1.235 +from the original file to the copied file, and that's why Mercurial
   1.236 +only propagates changes across copies until this point, and no
   1.237 +further.
   1.238 +
   1.239 +\subsection{How to make changes \emph{not} follow a copy}
   1.240 +
   1.241 +If, for some reason, you decide that this business of automatically
   1.242 +propagating changes across copies is not for you, simply use your
   1.243 +system's normal file copy command (on Unix-like systems, that's
   1.244 +\command{cp}) to make a copy of a file, then \hgcmd{add} the new copy
   1.245 +by hand.  Before you do so, though, please do reread
   1.246 +section~\ref{sec:daily:why-copy}, and make an informed decision that
   1.247 +this behaviour is not appropriate to your specific case.
   1.248 +
   1.249 +\subsection{Behaviour of the \hgcmd{copy} command}
   1.250 +
   1.251 +When you use the \hgcmd{copy} command, Mercurial makes a copy of each
   1.252 +source file as it currently stands in the working directory.  This
   1.253 +means that if you make some modifications to a file, then \hgcmd{copy}
   1.254 +it without first having committed those changes, the new copy will
   1.255 +also contain the modifications you have made up until that point.  (I
   1.256 +find this behaviour a little counterintuitive, which is why I mention
   1.257 +it here.)
   1.258 +
   1.259 +The \hgcmd{copy} command acts similarly to the Unix \command{cp}
   1.260 +command (you can use the \hgcmd{cp} alias if you prefer).  The last
   1.261 +argument is the \emph{destination}, and all prior arguments are
   1.262 +\emph{sources}.  If you pass it a single file as the source, and the
   1.263 +destination does not exist, it creates a new file with that name.
   1.264 +\interaction{daily.copy.simple}
   1.265 +If the destination is a directory, Mercurial copies its sources into
   1.266 +that directory.
   1.267 +\interaction{daily.copy.dir-dest}
   1.268 +Copying a directory is recursive, and preserves the directory
   1.269 +structure of the source.
   1.270 +\interaction{daily.copy.dir-src}
   1.271 +If the source and destination are both directories, the source tree is
   1.272 +recreated in the destination directory.
   1.273 +\interaction{daily.copy.dir-src-dest}
   1.274 +
   1.275 +As with the \hgcmd{rename} command, if you copy a file manually and
   1.276 +then want Mercurial to know that you've copied the file, simply use
   1.277 +the \hgopt{copy}{--after} option to \hgcmd{copy}.
   1.278 +\interaction{daily.copy.after}
   1.279 +
   1.280 +\section{Renaming files}
   1.281 +
   1.282 +It's rather more common to need to rename a file than to make a copy
   1.283 +of it.  The reason I discussed the \hgcmd{copy} command before talking
   1.284 +about renaming files is that Mercurial treats a rename in essentially
   1.285 +the same way as a copy.  Therefore, knowing what Mercurial does when
   1.286 +you copy a file tells you what to expect when you rename a file.
   1.287 +
   1.288 +When you use the \hgcmd{rename} command, Mercurial makes a copy of
   1.289 +each source file, then deletes it and marks the file as removed.
   1.290 +\interaction{daily.rename.rename}
   1.291 +The \hgcmd{status} command shows the newly copied file as added, and
   1.292 +the copied-from file as removed.
   1.293 +\interaction{daily.rename.status}
   1.294 +As with the results of a \hgcmd{copy}, we must use the
   1.295 +\hgopt{status}{-C} option to \hgcmd{status} to see that the added file
   1.296 +is really being tracked by Mercurial as a copy of the original, now
   1.297 +removed, file.
   1.298 +\interaction{daily.rename.status-copy}
   1.299 +
   1.300 +As with \hgcmd{remove} and \hgcmd{copy}, you can tell Mercurial about
   1.301 +a rename after the fact using the \hgopt{rename}{--after} option.  In
   1.302 +most other respects, the behaviour of the \hgcmd{rename} command, and
   1.303 +the options it accepts, are similar to the \hgcmd{copy} command.
   1.304 +
   1.305 +\subsection{Renaming files and merging changes}
   1.306 +
   1.307 +Since Mercurial's rename is implemented as copy-and-remove, the same
   1.308 +propagation of changes happens when you merge after a rename as after
   1.309 +a copy.
   1.310 +
   1.311 +If I modify a file, and you rename it to a new name, and then we merge
   1.312 +our respective changes, my modifications to the file under its
   1.313 +original name will be propagated into the file under its new name.
   1.314 +(This is something you might expect to ``simply work,'' but not all
   1.315 +revision control systems actually do this.)
   1.316 +
   1.317 +Whereas having changes follow a copy is a feature where you can
   1.318 +perhaps nod and say ``yes, that might be useful,'' it should be clear
   1.319 +that having them follow a rename is definitely important.  Without
   1.320 +this facility, it would simply be too easy for changes to become
   1.321 +orphaned when files are renamed.
   1.322 +
   1.323 +\subsection{Divergent renames and merging}
   1.324 +
   1.325 +The case of diverging names occurs when two developers start with a
   1.326 +file---let's call it \filename{foo}---in their respective
   1.327 +repositories.
   1.328 +
   1.329 +\interaction{rename.divergent.clone}
   1.330 +Anne renames the file to \filename{bar}.
   1.331 +\interaction{rename.divergent.rename.anne}
   1.332 +Meanwhile, Bob renames it to \filename{quux}.
   1.333 +\interaction{rename.divergent.rename.bob}
   1.334 +
   1.335 +I like to think of this as a conflict because each developer has
   1.336 +expressed different intentions about what the file ought to be named.
   1.337 +
   1.338 +What do you think should happen when they merge their work?
   1.339 +Mercurial's actual behaviour is that it always preserves \emph{both}
   1.340 +names when it merges changesets that contain divergent renames.
   1.341 +\interaction{rename.divergent.merge}
   1.342 +
   1.343 +Notice that Mercurial does warn about the divergent renames, but it
   1.344 +leaves it up to you to do something about the divergence after the merge.
   1.345 +
   1.346 +\subsection{Convergent renames and merging}
   1.347 +
   1.348 +Another kind of rename conflict occurs when two people choose to
   1.349 +rename different \emph{source} files to the same \emph{destination}.
   1.350 +In this case, Mercurial runs its normal merge machinery, and lets you
   1.351 +guide it to a suitable resolution.
   1.352 +
   1.353 +\subsection{Other name-related corner cases}
   1.354 +
   1.355 +Mercurial has a longstanding bug in which it fails to handle a merge
   1.356 +where one side has a file with a given name, while another has a
   1.357 +directory with the same name.  This is documented as~\bug{29}.
   1.358 +\interaction{issue29.go}
   1.359 +
   1.360 +\section{Recovering from mistakes}
   1.361 +
   1.362 +Mercurial has some useful commands that will help you to recover from
   1.363 +some common mistakes.
   1.364 +
   1.365 +The \hgcmd{revert} command lets you undo changes that you have made to
   1.366 +your working directory.  For example, if you \hgcmd{add} a file by
   1.367 +accident, just run \hgcmd{revert} with the name of the file you added,
   1.368 +and while the file won't be touched in any way, it won't be tracked
   1.369 +for adding by Mercurial any longer, either.  You can also use
   1.370 +\hgcmd{revert} to get rid of erroneous changes to a file.
   1.371 +
   1.372 +It's useful to remember that the \hgcmd{revert} command is useful for
   1.373 +changes that you have not yet committed.  Once you've committed a
   1.374 +change, if you decide it was a mistake, you can still do something
   1.375 +about it, though your options may be more limited.
   1.376 +
   1.377 +For more information about the \hgcmd{revert} command, and details
   1.378 +about how to deal with changes you have already committed, see
   1.379 +chapter~\ref{chap:undo}.
   1.380 +
   1.381 +%%% Local Variables: 
   1.382 +%%% mode: latex
   1.383 +%%% TeX-master: "00book"
   1.384 +%%% End: