# HG changeset patch # User Bryan O'Sullivan # Date 1161211624 25200 # Node ID ff9dc8bc2a8b28491dc3137e940f3f11d6694543 # Parent 321732566ac178447d4578a97731236cefb6fe51 More. Merge. Stuff. diff -r 321732566ac1 -r ff9dc8bc2a8b en/examples/tour --- 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 diff -r 321732566ac1 -r ff9dc8bc2a8b en/tour-basic.tex --- 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 +\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 diff -r 321732566ac1 -r ff9dc8bc2a8b en/tour-merge.tex --- 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"