changeset 102:ff9dc8bc2a8b

More. Merge. Stuff.

--- a/en/examples/tour	Wed Oct 18 14:11:51 2006 -0700
+++ b/en/examples/tour	Wed Oct 18 15:47:04 2006 -0700
@@ -66,6 +66,16 @@
 #$ name:
 
 export HGEDITOR='echo Added an extra line of output >'
+HGRCPATH_ORIG=$HGRCPATH
+export HGRCPATH=
+
+#$ name: commit-no-user
+
+hg commit
+
+#$ name:
+
+export HGRCPATH=$HGRCPATH_ORIG
 
 #$ name: commit
 

--- a/en/tour-basic.tex	Wed Oct 18 14:11:51 2006 -0700
+++ b/en/tour-basic.tex	Wed Oct 18 15:47:04 2006 -0700
@@ -356,6 +356,55 @@
 The \hgcmd{commit} command lets us create a new changeset; we'll
 usually refer to this as ``making a commit'' or ``committing''.  
 
+\subsection{Setting up a username}
+
+When you try to run \hgcmd{commit} for the first time, it may succeed
+immediately, or it may fail with an error message that looks like
+this.
+\interaction{tour.commit-no-user}
+If it succeeds for you, the chances are that either you already have a
+file called \sfilename{.hgrc} in your home directory, or an
+environment variable set named \envar{EMAIL}.
+
+When you commit, Mercurial wants to know what your name is, so that it
+can record it.  If you have created a \sfilename{.hgrc} file, it will
+look in there.  If it doesn't find something suitable, it will see if
+your \envar{EMAIL} address is set.  If neither of these is present, it
+will produce the error message you can see above.
+
+\subsubsection{Creating a Mercurial configuration file}
+
+To set a user name, use your favourite editor to create a file called
+\sfilename{.hgrc} in your home directory.  Mercurial will use this
+file to look up your personalised configuration settings.  The initial
+contents of your \sfilename{.hgrc} should look like this.
+\begin{codesample2}
+  # This is a Mercurial configuration file.
+  [ui]
+  username = Firstname Lastname <[e-mail]>
+\end{codesample2}
+The ``\texttt{[ui]}'' line begins a \emph{section} of the config file,
+so you can read the ``\texttt{username = ...}'' line as meaning ``set
+the value of the \texttt{username} item in the \texttt{ui} section''.
+A section continues until a new section begins, or the end of the
+file.  Mercurial ignores empty lines and treats any text from
+``\texttt{\#}'' to the end of a line as a comment.
+
+\subsubsection{Choosing a user name}
+
+You can use any text you like as the value of the \texttt{username}
+config item, since this information is for reading by other people,
+but for interpreting by Mercurial.  The convention that most people
+follow is to use their name and email address, as in the example
+above.
+
+\begin{note}
+  Mercurial's built-in web server obfuscates email addresses, to make
+  it more difficult for the email harvesting tools that spammers use.
+  This reduces the likelihood that you'll start receiving more junk
+  email if you publish a Mercurial repository on the web.
+\end{note}
+
 \subsection{Writing a commit message}
 
 When we commit a change, Mercurial drops us into a text editor, to
@@ -410,7 +459,7 @@
 all of the changes we've made, as reported by \hgcmd{status} and
 \hgcmd{diff}.
 
-\subsection{Admiring our new handywork}
+\subsection{Admiring our new handiwork}
 
 Once we've finished the commit, we can use the \hgcmd{tip} command to
 display the changeset we just created.  This command produces output

--- a/en/tour-merge.tex	Wed Oct 18 14:11:51 2006 -0700
+++ b/en/tour-merge.tex	Wed Oct 18 15:47:04 2006 -0700
@@ -44,6 +44,8 @@
 \interaction{tour.merge.pull}
 However, the \hgcmd{pull} command says something about ``heads''.  
 
+\subsection{Head changesets}
+
 A head is a change that has no descendants, or children, as they're
 also known.  The tip revision is thus a head, because the newest
 revision in a repository doesn't have any children, but a repository
@@ -68,6 +70,9 @@
 changesets.)  We can view the heads in a repository using the
 \hgcmd{heads} command.
 \interaction{tour.merge.heads}
+
+\subsection{Performing the merge}
+
 What happens if we try to use the normal \hgcmd{update} command to
 update to the new tip?
 \interaction{tour.merge.update}
@@ -89,6 +94,9 @@
 \emph{both} heads, which is reflected in both the output of
 \hgcmd{parents} and the contents of \filename{hello.c}.
 \interaction{tour.merge.parents}
+
+\subsection{Committing the results of the merge}
+
 Whenever we've done a merge, \hgcmd{parents} will display two parents
 until we \hgcmd{commit} the results of the merge.
 \interaction{tour.merge.commit}
@@ -102,6 +110,59 @@
 working directory has two parent changesets, and these become the
 parents of the new changeset.
 
+\section{Merging conflicting changes}
+
+Most merges are simple affairs, but sometimes you'll find yourself
+merging a change that you made with another, where both modify the
+same portions of the same files.  Unless both modifications are
+identical, this results in a \emph{conflict}, where you have to decide
+how to reconcile the different changes into something coherent.
+
+\section{Using an extension to simplify merging}
+
+The process of merging changes as outlined above is straightforward,
+but requires running three commands in sequence.
+\begin{codesample2}
+  hg pull
+  hg merge
+  hg commit -m 'Merged remote changes'
+\end{codesample2}
+In the case of the final commit, you also need to come up with a
+commit message, which is almost always going to be a piece of
+uninteresting ``boilerplate'' text.
+
+It would be nice to reduce the number of steps needed, if this were
+possible.  Indeed, Mercurial is distributed with an extension called
+\hgext{fetch} that does just this.
+
+Mercurial provides a flexible extension mechanism that lets people
+extend its functionality, while keeping the core of Mercurial small
+and easy to deal with.  Some extensions add new commands that you can
+use from the command line, while others work ``behind the scenes,''
+for example adding capabilities to the server.
+
+The \hgext{fetch} extension adds a new command called, not
+surprisingly, \hgcmd{fetch}.  This extension acts as a combination of
+\hgcmd{pull}, \hgcmd{update} and \hgcmd{merge}.  It begins by pulling
+changes from another repository into the current repository.  If it
+finds that the changes added a new head to the repository, it begins a
+merge, then commits the result of the merge with an
+automatically-generated commit message.  If no new heads were added,
+it updates the working directory to the new tip changeset.
+
+Enabling the \hgext{fetch} extension is easy.  Edit your
+\sfilename{.hgrc}, and either go to the \rcsection{extensions} section
+or create an \rcsection{extensions} section.  Then add a line that
+simply reads ``\Verb+fetch +''.
+\begin{codesample2}
+  [extensions]
+  fetch =
+\end{codesample2}
+(Normally, on the right-hand side of the ``\texttt{=}'' would appear
+the location of the extension, but since the \hgext{fetch} extension
+is in the standard distribution, Mercurial knows where to search for
+it.)
+
 %%% Local Variables: 
 %%% mode: latex
 %%% TeX-master: "00book"