# HG changeset patch # User Bryan O'Sullivan # Date 1163457136 28800 # Node ID a0f57b3e677ef261960ed36ce4f6b62f2efdafd8 # Parent 2fcead053b7abab7b66ea911ba0aefd0fbeb836e More concepts, this time working directory stuff. diff -r 2fcead053b7a -r a0f57b3e677e en/Makefile --- a/en/Makefile Mon Nov 13 13:21:29 2006 -0800 +++ b/en/Makefile Mon Nov 13 14:32:16 2006 -0800 @@ -31,7 +31,9 @@ tour-merge-conflict.svg \ tour-merge-merge.svg \ tour-merge-pull.svg \ - tour-merge-sep-repos.svg + tour-merge-sep-repos.svg \ + wdir.svg \ + wdir-after-commit.svg image-svg := $(filter %.svg,$(image-sources)) diff -r 2fcead053b7a -r a0f57b3e677e en/concepts.tex --- a/en/concepts.tex Mon Nov 13 13:21:29 2006 -0800 +++ b/en/concepts.tex Mon Nov 13 14:32:16 2006 -0800 @@ -206,11 +206,70 @@ \section{The working directory} -Mercurial's good ideas are not confined to the repository; it also -needs to manage the working directory. The \emph{dirstate} contains -Mercurial's knowledge of the working directory. This details which -revision(s) the working directory is updated to, and all files that -Mercurial is tracking in the working directory. +In the working directory, Mercurial stores a snapshot of the files +from the repository as of a particular changeset. + +The working directory ``knows'' which changeset it contains. When you +update the working directory to contain a particular changeset, +Mercurial looks up the appropriate revision of the manifest to find +out which files it was tracking at the time that changeset was +committed, and which revision of each file was then current. It then +recreates a copy of each of those files, with the same contents it had +when the changeset was committed. + +The \emph{dirstate} contains Mercurial's knowledge of the working +directory. This details which changeset the working directory is +updated to, and all of the files that Mercurial is tracking in the +working directory. + +Just as a revision of a revlog has room for two parents, so that it +can represent either a normal revision (with one parent) or a merge of +two earlier revisions, the dirstate has slots for two parents. When +you use the \hgcmd{update} command, the changeset that you update to +is stored in the ``first parent'' slot, and the null ID in the second. +When you \hgcmd{merge} with another changeset, the first parent +remains unchanged, and the second parent is filled in with the +changeset you're merging with. The \hgcmd{parents} command tells you +what the parents of the dirstate are. + +\subsection{What happens when you commit} + +The dirstate stores parent information for more than just book-keeping +purposes. Mercurial uses the parents of the dirstate as \emph{the + parents of a new changeset} when you perform a commit. + +\begin{figure}[ht] + \centering + \grafix{wdir} + \caption{The working directory can have two parents} + \label{fig:concepts:wdir} +\end{figure} + +Figure~\ref{fig:concepts:wdir} shows the normal state of the working +directory, where it has a single changeset as parent. That changeset +is the \emph{tip}, the newest changeset in the repository that has no +children. + +\begin{figure}[ht] + \centering + \grafix{wdir-after-commit} + \caption{The working directory gains new parents after a commit} + \label{fig:concepts:wdir-after-commit} +\end{figure} + +It's useful to think of the working directory as ``the changeset I'm +about to commit''. Any files that you tell Mercurial that you've +added, removed, renamed, or copied will be reflected in that +changeset, as will modifications to any files that Mercurial is +already tracking; the new changeset will have the parents of the +working directory as its parents. + +After a commit, Mercurial will update the parents of the working +directory, so that the first parent is the ID of the new changeset, +and the second is the null ID. This is illustrated in +figure~\ref{fig:concepts:wdir-after-commit}. + +\subsection{Other contents of the dirstate} Because Mercurial doesn't force you to tell it when you're modifying a file, it uses the dirstate to store some extra information so it can @@ -218,6 +277,9 @@ in the working directory, it stores the time that it last modified the file itself, and the size of the file at that time. +When you explicitly \hgcmd{add}, \hgcmd{remove}, \hgcmd{rename} or +\hgcmd{copy} files, the dirstate is updated each time. + When Mercurial is checking the states of files in the working directory, it first checks a file's modification time. If that has not changed, the file must not have been modified. If the file's size diff -r 2fcead053b7a -r a0f57b3e677e en/wdir-after-commit.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/en/wdir-after-commit.svg Mon Nov 13 14:32:16 2006 -0800 @@ -0,0 +1,373 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + dfbbb33f3fa3 + + + e7639888bb2f + + 7b064d8bac5e + + + + 000000000000 + + History in repository + + + + dfbbb33f3fa3 + + + + 000000000000 + + First parent + Second parent + Parents of working directory + + + Newchangeset + + diff -r 2fcead053b7a -r a0f57b3e677e en/wdir.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/en/wdir.svg Mon Nov 13 14:32:16 2006 -0800 @@ -0,0 +1,348 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + e7639888bb2f + + 7b064d8bac5e + + + 000000000000 + + + History in repository + + + + + e7639888bb2f + + + + 000000000000 + + First parent + Second parent + + Parents of working directory + + + +