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. - - 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" + 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. + - - 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. + 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. + + + + + 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,10 +1516,55 @@ <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 + diff -r 83540574ee49 -r 743dc55775fe en/ch06-filenames.xml --- a/en/ch06-filenames.xml Sat Apr 18 17:38:07 2009 +0200 +++ b/en/ch06-filenames.xml Sat Apr 18 17:45:54 2009 +0200 @@ -27,8 +27,8 @@ before continuing with the current directory. &interaction.filenames.dirs; + - Running commands without any file names @@ -70,8 +70,8 @@ role="hg-cmd">hg root command. &interaction.filenames.wdir-relname; + - Telling you what's going on @@ -85,17 +85,17 @@ The principle here is of least surprise. If you've exactly named a file on the command line, there's no point in repeating it back at you. If - Mercurial is acting on a file implicitly, + Mercurial is acting on a file implicitly, e.g. because you provided no names, or a directory, or a pattern (see - below), it's safest to tell you what it's doing. + below), it is safest to tell you what files it's operating on. For commands that behave this way, you can silence them using the option. You can also get them to print the name of every file, even those you've named explicitly, using the option. + - Using patterns to identify files @@ -194,9 +194,9 @@ example illustrates the difference between the two. &interaction.filenames.glob.star-starstar; - + Regular expression matching with <literal>re</literal> patterns @@ -227,9 +227,9 @@ string; it doesn't look for a match anywhere within the string. To match anywhere in a string, start your pattern with .*. - + Filtering files @@ -266,14 +266,65 @@ pattern. &interaction.filenames.filter.exclude; + - - Ignoring unwanted files and directories + Permanently ignoring unwanted files and directories + + When you create a new repository, the chances are + that over time it will grow to contain files that ought to + not be managed by Mercurial, but which you + don't want to see listed every time you run hg + status. For instance, build products + are files that are created as part of a build but which should + not be managed by a revision control system. The most common + build products are output files produced by software tools such + as compilers. As another example, many text editors litter a + directory with lock files, temporary working files, and backup + files, which it also makes no sense to manage. + + To have Mercurial permanently ignore such files, create a + file named .hgignore in the root of your + repository. You should hg + add this file so that it gets tracked with the rest of + your repository contents, since your collaborators will probably + find it useful too. + + By default, the .hgignore file should + contain a list of regular expressions, one per line. Empty + lines are skipped. Most people prefer to describe the files they + want to ignore using the glob syntax that we + described above, so a typical .hgignore + file will start with this directive: - XXX. + syntax: glob + + This tells Mercurial to interpret the lines that follow as + glob patterns, not regular expressions. + + Here is a typical-looking .hgignore + file. + + syntax: glob +# This line is a comment, and will be skipped. +# Empty lines are skipped too. +# Backup files left behind by the Emacs editor. +*~ + +# Lock files used by the Emacs editor. +# Notice that the "#" character is quoted with a backslash. +# This prevents it from being interpreted as starting a comment. +.\#* + +# Temporary files used by the vim editor. +.*.swp + +# A hidden file created by the Mac OS X Finder. +.DS_Store + + Case sensitivity @@ -361,8 +412,8 @@ conflict between the two file names that the filesystem would treat as the same, and forbid the update or merge from occurring. + - Fixing a case conflict @@ -388,15 +439,6 @@ hg update your working directory to that changeset on a Windows or MacOS system, but you can continue development unimpeded. - - - Prior to version 0.9.3, Mercurial did not use a case - safe repository storage mechanism, and did not detect case - folding conflicts. If you are using an older version of - Mercurial on Windows or MacOS, I strongly recommend that you - upgrade. - - diff -r 83540574ee49 -r 743dc55775fe en/ch07-branch.xml --- a/en/ch07-branch.xml Sat Apr 18 17:38:07 2009 +0200 +++ b/en/ch07-branch.xml Sat Apr 18 17:45:54 2009 +0200 @@ -128,7 +128,7 @@ Mercurial stores tags in a normal revision-controlled file in your repository. If you've created any tags, you'll find - them in a file named .hgtags. When you run the hg tag command, Mercurial modifies this file, then automatically commits the change to it. This @@ -170,8 +170,8 @@ location of the error, which you can then fix and commit. You should then run hg tags again, just to be sure that your fix is correct. + - Tags and cloning @@ -195,8 +195,8 @@ project's history in the new repository, but not the tag you might have expected. + - When permanent tags are too much @@ -221,9 +221,9 @@ controlled. Any tags you create using remain strictly local to the repository you're currently working in. - + The flow of changes&emdash;big picture vs. little @@ -252,8 +252,8 @@ merging changes. They expose the narrative of how the code was developed. + - Managing big-picture branches in repositories @@ -285,8 +285,8 @@ the myproject repository. &interaction.branch-repo.new; + - Don't repeat yourself: merging across branches @@ -308,8 +308,8 @@ push back to the main branch. &interaction.branch-repo.merge; + - Naming branches within one repository @@ -408,8 +408,8 @@ In practice, this is something you won't do very often, as branch names tend to have fairly long lifetimes. (This isn't a rule, just an observation.) + - Dealing with multiple named branches in a repository @@ -454,8 +454,8 @@ introduces a new head. &interaction.branch-named.foo-commit; + - Branch names and merging @@ -496,8 +496,8 @@ Mercurial will choose the right (bleeding-edge) branch name when I pull and merge from stable. + - Branch naming is generally useful @@ -522,7 +522,6 @@ /.hgrc. [hooks] pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch -