hgbook
changeset 102:ff9dc8bc2a8b
More. Merge. Stuff.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Wed Oct 18 15:47:04 2006 -0700 (2006-10-18) |
parents | 321732566ac1 |
children | 5b80c922ebdd |
files | en/examples/tour en/tour-basic.tex en/tour-merge.tex |
line diff
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"