Option naming consistency

# HG changeset patch # User Raphael Borun Das Gupta # Date 1240069554 -7200 # Node ID 743dc55775fef62bd87e178f3bb9de980fbc5027 # Parent 83540574ee49df74141d5c36ec9929ac3efdc502# Parent 29f0f79cf6146b747b2cbc9afe658f6b23ee6810 Merged upstream diff -r 83540574ee49 -r 743dc55775fe en/ch01-tour-basic.xml --- a/en/ch01-tour-basic.xml Sat Apr 18 17:38:07 2009 +0200 +++ b/en/ch01-tour-basic.xml Sat Apr 18 17:45:54 2009 +0200 @@ -131,7 +131,7 @@ &interaction.tour.clone; - One advantage of using hg + One advantage of using hg clone is that, as we can see above, it lets us clone repositories over the network. Another is that it remembers where we cloned from, which we'll find useful soon when we @@ -233,7 +233,7 @@ the text message that the creator of the changeset entered to describe the changeset. - Some changesets, such as the first in the list above, + Some changesets, such as the first in the list above, have a tag field. A tag is another way to identify a changeset, by giving it an easy-to-remember name. (The tag named tip is special: it @@ -364,7 +364,7 @@ &interaction.tour.log-vp; - The option is + The option is tremendously useful, so it's well worth remembering. @@ -410,7 +410,7 @@ role="hg-opt-log">--rev arguments. - If you are using short options, you can save typing by + If you are using short options, you can save typing by running them together. For example, the command hg log -v -p -r 2 can be written as hg log -vpr2. @@ -430,7 +430,7 @@ Option naming consistency - Almost always, Mercurial commands use consistent option + Almost always, Mercurial commands use consistent option names to refer to the same concepts. For instance, if a command deals with changesets, you'll always identify them with or - A good distributed revision control tool, such as - Mercurial, will support both models. You and your - collaborators can then structure how you work together based - on your own needs and preferences, not on what contortions - your tools force you into. - + A good distributed revision control tool will + support both models. You and your collaborators can then + structure how you work together based on your own needs and + preferences, not on what contortions your tools force you + into. Where collaboration meets branch management @@ -409,16 +454,16 @@ Even though this subject is intimately related to how your team collaborates, it's dense enough to merit treatment of its own, in . - + The technical side of sharing The remainder of this chapter is devoted to the question of - serving data to your collaborators. - + sharing changes with your collaborators. + Informal sharing with <command role="hg-cmd">hg serve</command> @@ -495,9 +540,9 @@ find out what URL you should send to your collaborators, start it with the option. - + Using the Secure Shell (ssh) protocol @@ -506,11 +551,11 @@ protocol. To use this successfully, you may have to do a little bit of configuration on the client or server sides. - If you're not familiar with ssh, it's a network protocol - that lets you securely communicate with another computer. To - use it with Mercurial, you'll be setting up one or more user - accounts on a server so that remote users can log in and execute - commands. + If you're not familiar with ssh, it's the name of + both a command and a network protocol that let you securely + communicate with another computer. To use it with Mercurial, + you'll be setting up one or more user accounts on a server so + that remote users can log in and execute commands. (If you are familiar with ssh, you'll probably find some of the material that follows to be elementary @@ -569,8 +614,8 @@ absolute path on the server, begin the path component with two slashes, as in this example. ssh://server//absolute/path - - + + Finding an ssh client for your system @@ -582,44 +627,44 @@ unlikely event that it isn't present, take a look at your system documentation to figure out how to install it. - On Windows, you'll first need to download a suitable ssh - client. There are two alternatives. + On Windows, the TortoiseHg package is bundled + with a version of Simon Tatham's excellent + plink command, and you should not need to + do any further configuration. + + + + Generating a key pair + + To avoid the need to repetitively type a + password every time you need to use your ssh client, I + recommend generating a key pair. + + + Key pairs are not mandatory + + Mercurial knows nothing about ssh authentication or key + pairs. You can, if you like, safely ignore this section and + the one that follows until you grow tired of repeatedly + typing ssh passwords. + + - Simon Tatham's excellent PuTTY package - web:putty provides a complete suite - of ssh client commands. - - If you have a high tolerance for pain, you can - use the Cygwin port of OpenSSH. - - In either case, you'll need to edit your hg.ini file to - tell Mercurial where to find the actual client command. For - example, if you're using PuTTY, you'll need to use the - plink command as a command-line ssh - client. - [ui] -ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key" - - - The path to plink shouldn't contain - any whitespace characters, or Mercurial may not be able to - run it correctly (so putting it in C:\Program Files is probably - not a good idea). - - - - - Generating a key pair - - To avoid the need to repetitively type a password every - time you need to use your ssh client, I recommend generating a - key pair. On a Unix-like system, the - ssh-keygen command will do the trick. On - Windows, if you're using PuTTY, the - puttygen command is what you'll - need. + + On a Unix-like system, the + ssh-keygen command will do the + trick. + On Windows, if you're using TortoiseHg, you may need + to download a command named puttygen + from the + PuTTY web site to generate a key pair. See + the + puttygen documentation for + details of how use the command. + + When you generate a key pair, it's usually highly advisable to protect it with a @@ -642,7 +687,6 @@ public key to a file of your choosing, or paste it from the window it's displayed in straight into the authorized_keys file. - Using an authentication agent @@ -663,21 +707,34 @@ judgment as to whether this is an acceptable risk. It certainly saves a lot of repeated typing. - On Unix-like systems, the agent is called - ssh-agent, and it's often run automatically - for you when you log in. You'll need to use the - ssh-add command to add passphrases to the - agent's store. On Windows, if you're using PuTTY, the - pageant command acts as the agent. It adds - an icon to your system tray that will let you manage stored - passphrases. - - + + + On Unix-like systems, the agent is called + ssh-agent, and it's often run + automatically for you when you log in. You'll need to use + the ssh-add command to add passphrases + to the agent's store. + + + On Windows, if you're using TortoiseHg, the + pageant command acts as the agent. As + with puttygen, you'll need to download + pageant from the PuTTY web + site and read its + documentation. The pageant + command adds an icon to your system tray that will let you + manage stored passphrases. + + + + Configuring the server side properly Because ssh can be fiddly to set up if you're new to it, - there's a variety of things that can go wrong. Add Mercurial + a variety of things can go wrong. Add Mercurial on top, and there's plenty more scope for head-scratching. Most of these potential problems occur on the server side, not the client side. The good news is that once you've gotten a @@ -821,7 +878,6 @@ If you run into problems with Mercurial and ssh at this point, try using the option to get a clearer picture of what's going on. - Using compression with ssh @@ -842,31 +898,40 @@ accept a option which turns on compression. You can easily edit your ~/.hgrc to enable compression for - all of Mercurial's uses of the ssh protocol. + all of Mercurial's uses of the ssh protocol. Here is how to + do so for regular ssh on Unix-like systems, + for example. [ui] ssh = ssh -C - If you use ssh, you can configure it to - always use compression when talking to your server. To do - this, edit your .ssh/config file (which may not - yet exist), as follows. + If you use ssh on a + Unix-like system, you can configure it to always use + compression when talking to your server. To do this, edit + your .ssh/config file + (which may not yet exist), as follows. + Host hg Compression yes HostName hg.example.com - This defines an alias, hg. When you - use it on the ssh command line or in a - Mercurial ssh-protocol URL, it will cause + + This defines a hostname alias, + hg. When you use that hostname on the + ssh command line or in a Mercurial + ssh-protocol URL, it will cause ssh to connect to hg.example.com and use compression. This gives you both a shorter name to type and compression, each of which is a good thing in its own right. - + Serving over HTTP using CGI + The simplest way to host one or more repositories in a + permanent way is to use a web server and Mercurial's CGI + support. + Depending on how ambitious you are, configuring Mercurial's CGI interface can take anything from a few moments to several hours. @@ -877,13 +942,20 @@ your web server's configuration. - Configuring a web server is a complex, fiddly, and - highly system-dependent activity. I can't possibly give you - instructions that will cover anything like all of the cases - you will encounter. Please use your discretion and judgment in - following the sections below. Be prepared to make plenty of - mistakes, and to spend a lot of time reading your server's - error logs. + High pain tolerance required + + Configuring a web server is a complex, fiddly, + and highly system-dependent activity. I can't possibly give + you instructions that will cover anything like all of the + cases you will encounter. Please use your discretion and + judgment in following the sections below. Be prepared to make + plenty of mistakes, and to spend a lot of time reading your + server's error logs. + + If you don't have a strong stomach for tweaking + configurations over and over, or a compelling need to host + your own services, you might want to try one of the public + hosting services that I mentioned earlier. @@ -893,9 +965,10 @@ aspects of your system's setup. - Do you have a web server installed at all? - Mac OS X ships with Apache, but many other systems may not - have a web server installed. + Do you have a web server installed + at all? Mac OS X and some Linux distributions ship with + Apache, but many other systems may not have a web server + installed. If you have a web server installed, is it actually running? On most systems, even if one is @@ -917,8 +990,8 @@ repositories. And lighttpd is undeniably much easier to get started with than Apache. - - + + Basic CGI configuration @@ -1048,8 +1121,8 @@ At this point, when you try to reload the page, you should be presented with a nice HTML view of your repository's history. Whew! - + Configuring lighttpd @@ -1084,9 +1157,9 @@ configure than Apache, even though I've used Apache for over a decade, and this was my first exposure to lighttpd. - + Sharing multiple repositories with one CGI script @@ -1215,14 +1288,16 @@ file. - If multiple repositories have the same virtual path, - hgwebdir.cgi will not - report an error. Instead, it will behave - unpredictably. + Beware duplicate virtual paths + + If several repositories have the same + virtual path, hgwebdir.cgi will not report + an error. Instead, it will behave unpredictably. - + Downloading source archives @@ -1235,8 +1310,7 @@ you'll need to add an allow_archive item to the web section of your ~/.hgrc. - + role="special">~/.hgrc; see below for details. Web configuration options @@ -1318,9 +1392,28 @@ style: Controls the template Mercurial uses to display the web interface. Mercurial - ships with two web templates, named - default and gitweb - (the latter is much more visually attractive). You can + ships with several web templates. + + + coal is monochromatic. + + + gitweb emulates the visual + style of git's web interface. + + + monoblue uses solid blues and + greys. + + + paper is the default. + + + spartan was the default for a + long time. + + + You can also specify a custom template of your own; see for details. Here, you can see how to enable the gitweb @@ -1361,8 +1454,8 @@ interface. This overrides the default name, which is the last component of the repository's path. - + Options specific to the <command role="hg-cmd">hg serve</command> command @@ -1400,8 +1493,8 @@ Integer. The TCP port number on which the server should listen. The default port number used is 8000. - + Choosing the right <filename role="special">~/.hgrc</filename> file to add <literal @@ -1423,12 +1516,57 @@ <filename role="special">~/.hgrc</filename> file in the home directory of the user ID that runs your web server, or add those settings to a system-wide <filename - role="special">~/.hgrc</filename> file.</para> - - + role="special">hgrc</filename> file.</para> </sect3> </sect2> </sect1> + + <sect1> + <title>System-wide configuration + + On Unix-like systems shared by multiple users (such as a + server to which people publish changes), it often makes sense to + set up some global default behaviors, such as what theme to use + in web interfaces. + + If a file named /etc/mercurial/hgrc + exists, Mercurial will read it at startup time and apply any + configuration settings it finds in that file. It will also look + for files ending in a .rc extension in a + directory named /etc/mercurial/hgrc.d, and + apply any configuration settings it finds in each of those + files. + + + Making Mercurial more trusting + + One situation in which a global hgrc + can be useful is if users are pulling changes owned by other + users. By default, Mercurial will not trust most of the + configuration items in a .hg/hgrc file + inside a repository that is owned by a different user. If we + clone or pull changes from such a repository, Mercurial will + print a warning stating that it does not trust their + .hg/hgrc. + + If everyone in a particular Unix group is on the same team + and should trust each other's + configuration settings, or we want to trust particular users, + we can override Mercurial's skeptical defaults by creating a + system-wide hgrc file such as the + following: + + # Save this as e.g. /etc/mercurial/hgrc.d/trust.rc +[trusted] +# Trust all entries in any hgrc file owned by the "editors" or +# "www-data" groups. +groups = editors, www-data + +# Trust entries in hgrc files owned by the following users. +users = apache, bobo + + +