1.1 --- a/en/examples/tour	Wed Oct 18 14:11:51 2006 -0700
     1.2 +++ b/en/examples/tour	Wed Oct 18 15:47:04 2006 -0700
     1.3 @@ -66,6 +66,16 @@
     1.4  #$ name:
     1.5  
     1.6  export HGEDITOR='echo Added an extra line of output >'
     1.7 +HGRCPATH_ORIG=$HGRCPATH
     1.8 +export HGRCPATH=
     1.9 +
    1.10 +#$ name: commit-no-user
    1.11 +
    1.12 +hg commit
    1.13 +
    1.14 +#$ name:
    1.15 +
    1.16 +export HGRCPATH=$HGRCPATH_ORIG
    1.17  
    1.18  #$ name: commit
    1.19  

     2.1 --- a/en/tour-basic.tex	Wed Oct 18 14:11:51 2006 -0700
     2.2 +++ b/en/tour-basic.tex	Wed Oct 18 15:47:04 2006 -0700
     2.3 @@ -356,6 +356,55 @@
     2.4  The \hgcmd{commit} command lets us create a new changeset; we'll
     2.5  usually refer to this as ``making a commit'' or ``committing''.  
     2.6  
     2.7 +\subsection{Setting up a username}
     2.8 +
     2.9 +When you try to run \hgcmd{commit} for the first time, it may succeed
    2.10 +immediately, or it may fail with an error message that looks like
    2.11 +this.
    2.12 +\interaction{tour.commit-no-user}
    2.13 +If it succeeds for you, the chances are that either you already have a
    2.14 +file called \sfilename{.hgrc} in your home directory, or an
    2.15 +environment variable set named \envar{EMAIL}.
    2.16 +
    2.17 +When you commit, Mercurial wants to know what your name is, so that it
    2.18 +can record it.  If you have created a \sfilename{.hgrc} file, it will
    2.19 +look in there.  If it doesn't find something suitable, it will see if
    2.20 +your \envar{EMAIL} address is set.  If neither of these is present, it
    2.21 +will produce the error message you can see above.
    2.22 +
    2.23 +\subsubsection{Creating a Mercurial configuration file}
    2.24 +
    2.25 +To set a user name, use your favourite editor to create a file called
    2.26 +\sfilename{.hgrc} in your home directory.  Mercurial will use this
    2.27 +file to look up your personalised configuration settings.  The initial
    2.28 +contents of your \sfilename{.hgrc} should look like this.
    2.29 +\begin{codesample2}
    2.30 +  # This is a Mercurial configuration file.
    2.31 +  [ui]
    2.32 +  username = Firstname Lastname <email.address@domain.net>
    2.33 +\end{codesample2}
    2.34 +The ``\texttt{[ui]}'' line begins a \emph{section} of the config file,
    2.35 +so you can read the ``\texttt{username = ...}'' line as meaning ``set
    2.36 +the value of the \texttt{username} item in the \texttt{ui} section''.
    2.37 +A section continues until a new section begins, or the end of the
    2.38 +file.  Mercurial ignores empty lines and treats any text from
    2.39 +``\texttt{\#}'' to the end of a line as a comment.
    2.40 +
    2.41 +\subsubsection{Choosing a user name}
    2.42 +
    2.43 +You can use any text you like as the value of the \texttt{username}
    2.44 +config item, since this information is for reading by other people,
    2.45 +but for interpreting by Mercurial.  The convention that most people
    2.46 +follow is to use their name and email address, as in the example
    2.47 +above.
    2.48 +
    2.49 +\begin{note}
    2.50 +  Mercurial's built-in web server obfuscates email addresses, to make
    2.51 +  it more difficult for the email harvesting tools that spammers use.
    2.52 +  This reduces the likelihood that you'll start receiving more junk
    2.53 +  email if you publish a Mercurial repository on the web.
    2.54 +\end{note}
    2.55 +
    2.56  \subsection{Writing a commit message}
    2.57  
    2.58  When we commit a change, Mercurial drops us into a text editor, to
    2.59 @@ -410,7 +459,7 @@
    2.60  all of the changes we've made, as reported by \hgcmd{status} and
    2.61  \hgcmd{diff}.
    2.62  
    2.63 -\subsection{Admiring our new handywork}
    2.64 +\subsection{Admiring our new handiwork}
    2.65  
    2.66  Once we've finished the commit, we can use the \hgcmd{tip} command to
    2.67  display the changeset we just created.  This command produces output

     3.1 --- a/en/tour-merge.tex	Wed Oct 18 14:11:51 2006 -0700
     3.2 +++ b/en/tour-merge.tex	Wed Oct 18 15:47:04 2006 -0700
     3.3 @@ -44,6 +44,8 @@
     3.4  \interaction{tour.merge.pull}
     3.5  However, the \hgcmd{pull} command says something about ``heads''.  
     3.6  
     3.7 +\subsection{Head changesets}
     3.8 +
     3.9  A head is a change that has no descendants, or children, as they're
    3.10  also known.  The tip revision is thus a head, because the newest
    3.11  revision in a repository doesn't have any children, but a repository
    3.12 @@ -68,6 +70,9 @@
    3.13  changesets.)  We can view the heads in a repository using the
    3.14  \hgcmd{heads} command.
    3.15  \interaction{tour.merge.heads}
    3.16 +
    3.17 +\subsection{Performing the merge}
    3.18 +
    3.19  What happens if we try to use the normal \hgcmd{update} command to
    3.20  update to the new tip?
    3.21  \interaction{tour.merge.update}
    3.22 @@ -89,6 +94,9 @@
    3.23  \emph{both} heads, which is reflected in both the output of
    3.24  \hgcmd{parents} and the contents of \filename{hello.c}.
    3.25  \interaction{tour.merge.parents}
    3.26 +
    3.27 +\subsection{Committing the results of the merge}
    3.28 +
    3.29  Whenever we've done a merge, \hgcmd{parents} will display two parents
    3.30  until we \hgcmd{commit} the results of the merge.
    3.31  \interaction{tour.merge.commit}
    3.32 @@ -102,6 +110,59 @@
    3.33  working directory has two parent changesets, and these become the
    3.34  parents of the new changeset.
    3.35  
    3.36 +\section{Merging conflicting changes}
    3.37 +
    3.38 +Most merges are simple affairs, but sometimes you'll find yourself
    3.39 +merging a change that you made with another, where both modify the
    3.40 +same portions of the same files.  Unless both modifications are
    3.41 +identical, this results in a \emph{conflict}, where you have to decide
    3.42 +how to reconcile the different changes into something coherent.
    3.43 +
    3.44 +\section{Using an extension to simplify merging}
    3.45 +
    3.46 +The process of merging changes as outlined above is straightforward,
    3.47 +but requires running three commands in sequence.
    3.48 +\begin{codesample2}
    3.49 +  hg pull
    3.50 +  hg merge
    3.51 +  hg commit -m 'Merged remote changes'
    3.52 +\end{codesample2}
    3.53 +In the case of the final commit, you also need to come up with a
    3.54 +commit message, which is almost always going to be a piece of
    3.55 +uninteresting ``boilerplate'' text.
    3.56 +
    3.57 +It would be nice to reduce the number of steps needed, if this were
    3.58 +possible.  Indeed, Mercurial is distributed with an extension called
    3.59 +\hgext{fetch} that does just this.
    3.60 +
    3.61 +Mercurial provides a flexible extension mechanism that lets people
    3.62 +extend its functionality, while keeping the core of Mercurial small
    3.63 +and easy to deal with.  Some extensions add new commands that you can
    3.64 +use from the command line, while others work ``behind the scenes,''
    3.65 +for example adding capabilities to the server.
    3.66 +
    3.67 +The \hgext{fetch} extension adds a new command called, not
    3.68 +surprisingly, \hgcmd{fetch}.  This extension acts as a combination of
    3.69 +\hgcmd{pull}, \hgcmd{update} and \hgcmd{merge}.  It begins by pulling
    3.70 +changes from another repository into the current repository.  If it
    3.71 +finds that the changes added a new head to the repository, it begins a
    3.72 +merge, then commits the result of the merge with an
    3.73 +automatically-generated commit message.  If no new heads were added,
    3.74 +it updates the working directory to the new tip changeset.
    3.75 +
    3.76 +Enabling the \hgext{fetch} extension is easy.  Edit your
    3.77 +\sfilename{.hgrc}, and either go to the \rcsection{extensions} section
    3.78 +or create an \rcsection{extensions} section.  Then add a line that
    3.79 +simply reads ``\Verb+fetch +''.
    3.80 +\begin{codesample2}
    3.81 +  [extensions]
    3.82 +  fetch =
    3.83 +\end{codesample2}
    3.84 +(Normally, on the right-hand side of the ``\texttt{=}'' would appear
    3.85 +the location of the extension, but since the \hgext{fetch} extension
    3.86 +is in the standard distribution, Mercurial knows where to search for
    3.87 +it.)
    3.88 +
    3.89  %%% Local Variables: 
    3.90  %%% mode: latex
    3.91  %%% TeX-master: "00book"