1.1 --- a/en/concepts.tex	Mon Nov 13 13:21:29 2006 -0800
     1.2 +++ b/en/concepts.tex	Mon Nov 13 14:34:57 2006 -0800
     1.3 @@ -206,11 +206,70 @@
     1.4  
     1.5  \section{The working directory}
     1.6  
     1.7 -Mercurial's good ideas are not confined to the repository; it also
     1.8 -needs to manage the working directory.  The \emph{dirstate} contains
     1.9 -Mercurial's knowledge of the working directory.  This details which
    1.10 -revision(s) the working directory is updated to, and all files that
    1.11 -Mercurial is tracking in the working directory.
    1.12 +In the working directory, Mercurial stores a snapshot of the files
    1.13 +from the repository as of a particular changeset.
    1.14 +
    1.15 +The working directory ``knows'' which changeset it contains.  When you
    1.16 +update the working directory to contain a particular changeset,
    1.17 +Mercurial looks up the appropriate revision of the manifest to find
    1.18 +out which files it was tracking at the time that changeset was
    1.19 +committed, and which revision of each file was then current.  It then
    1.20 +recreates a copy of each of those files, with the same contents it had
    1.21 +when the changeset was committed.
    1.22 +
    1.23 +The \emph{dirstate} contains Mercurial's knowledge of the working
    1.24 +directory.  This details which changeset the working directory is
    1.25 +updated to, and all of the files that Mercurial is tracking in the
    1.26 +working directory.
    1.27 +
    1.28 +Just as a revision of a revlog has room for two parents, so that it
    1.29 +can represent either a normal revision (with one parent) or a merge of
    1.30 +two earlier revisions, the dirstate has slots for two parents.  When
    1.31 +you use the \hgcmd{update} command, the changeset that you update to
    1.32 +is stored in the ``first parent'' slot, and the null ID in the second.
    1.33 +When you \hgcmd{merge} with another changeset, the first parent
    1.34 +remains unchanged, and the second parent is filled in with the
    1.35 +changeset you're merging with.  The \hgcmd{parents} command tells you
    1.36 +what the parents of the dirstate are.
    1.37 +
    1.38 +\subsection{What happens when you commit}
    1.39 +
    1.40 +The dirstate stores parent information for more than just book-keeping
    1.41 +purposes.  Mercurial uses the parents of the dirstate as \emph{the
    1.42 +  parents of a new changeset} when you perform a commit.
    1.43 +
    1.44 +\begin{figure}[ht]
    1.45 +  \centering
    1.46 +  \grafix{wdir}
    1.47 +  \caption{The working directory can have two parents}
    1.48 +  \label{fig:concepts:wdir}
    1.49 +\end{figure}
    1.50 +
    1.51 +Figure~\ref{fig:concepts:wdir} shows the normal state of the working
    1.52 +directory, where it has a single changeset as parent.  That changeset
    1.53 +is the \emph{tip}, the newest changeset in the repository that has no
    1.54 +children.
    1.55 +
    1.56 +\begin{figure}[ht]
    1.57 +  \centering
    1.58 +  \grafix{wdir-after-commit}
    1.59 +  \caption{The working directory gains new parents after a commit}
    1.60 +  \label{fig:concepts:wdir-after-commit}
    1.61 +\end{figure}
    1.62 +
    1.63 +It's useful to think of the working directory as ``the changeset I'm
    1.64 +about to commit''.  Any files that you tell Mercurial that you've
    1.65 +added, removed, renamed, or copied will be reflected in that
    1.66 +changeset, as will modifications to any files that Mercurial is
    1.67 +already tracking; the new changeset will have the parents of the
    1.68 +working directory as its parents.
    1.69 +
    1.70 +After a commit, Mercurial will update the parents of the working
    1.71 +directory, so that the first parent is the ID of the new changeset,
    1.72 +and the second is the null ID.  This is illustrated in
    1.73 +figure~\ref{fig:concepts:wdir-after-commit}.
    1.74 +
    1.75 +\subsection{Other contents of the dirstate}
    1.76  
    1.77  Because Mercurial doesn't force you to tell it when you're modifying a
    1.78  file, it uses the dirstate to store some extra information so it can
    1.79 @@ -218,6 +277,9 @@
    1.80  in the working directory, it stores the time that it last modified the
    1.81  file itself, and the size of the file at that time.  
    1.82  
    1.83 +When you explicitly \hgcmd{add}, \hgcmd{remove}, \hgcmd{rename} or
    1.84 +\hgcmd{copy} files, the dirstate is updated each time.
    1.85 +
    1.86  When Mercurial is checking the states of files in the working
    1.87  directory, it first checks a file's modification time.  If that has
    1.88  not changed, the file must not have been modified.  If the file's size