Mirada (transl., Spanish feminine noun): A look or gaze, especially one of particular meaning or interest. Mid-resolution InfRAreD Astronomical Spectrograph System Design Note: Notes on Mercurial (hg) Usage S. N. Raines On behalf of the MIRADAS Consortium 2013-01-08 058_001 mi_058_001_hg_notes Full Contents Full Contents ii Executive Summary v Useful Mercurial References vii 1 Orientation 1 1.1 Mercurial Interfaces . 1 1.2 File Concepts . 1 1.2.1 Recommendations for LATEX document text . 2 2 Required Mercurial Reading 3 2.1 Other Useful References . 4 2.1.1 Obtaining help . 4 2.1.2 Three reference cards . 4 2.1.3 Manuals . 4 3 Mercurial Installation 9 3.1 Mac Installation . 9 3.2 Windows Installation . 9 3.3 Linux Installation . 9 3.3.1 Check installed Python . 9 3.3.2 Acquire code . 9 3.3.3 Installation . 9 3.3.4 Add hg to path . 10 3.3.5 Test the install . 10 3.4 Set up .hgrc file . 10 4 Example Mercurial Structure and Use 13 4.1 Instlab Structure . 13 4.2 My Workflow . 13 4.2.1 Update the master repository . 14 4.2.2 Keep a USB drive copy . 14 4.3 Examples with commands . 14 4.3.1 Working with others . 15 4.4 What Files are Tracked? (.hgignore)........................ 15 ii Processed on: January 8, 2013 at 14:42. 058_001 iii / 17 Executive Summary This brief document will point to some useful on-line guides for using Mercurial, a distributed version control system tool. Mercurial may be used for any text document, be it source code or non-software, e.g. manuals. v Useful Mercurial References Steve Borho. TortoiseHg, 01 2013. URL http://tortoisehg.bitbucket.org/. Adrian Buehlmann. A Tutorial on Using Mercurial, 2012. URL http://mercurial. selenic.com/wiki/Tutorial. Adrian Buehlmann. Understanding Mercurial, 2012. URL http://mercurial. selenic.com/wiki/UnderstandingMercurial. Adrian Buehlmann. Learning Mercurial in Workflows, 2012. URL http://mercurial. selenic.com/guide. Adrian Buehlmann. Other Tools, 01 2013. URL http://mercurial.selenic.com/ wiki/OtherTools. Steve Losh. hg tip, 2013. URL hgtip.com/tips/beginner. Matt Mackall. hg Mercurial source code management system, 2012. URL http://www. selenic.com/mercurial/hg.1.html. Mercurial, Arne Babenhauserheide, Steve Losh, and David Soria Parra. Mercurial, 2012. URL http://mercurial.selenic.com/. William Stafford Noble. A Quick Guide to Organizing Computational Biology Projects. PLoS Computational Biology, 5(7):e1000424, July 2009. doi: 10.1371/journal.pcbi.1000424. g001. URL http://dx.plos.org/10.1371/journal.pcbi.1000424.g001. Bryan O’Sullivan. Mercurial: The Definitive Guide, 2009. URL http://www.selenic. com/mercurial/hg.1.html. Bryan O’Sullivan. hgrc Configuration files for Mercurial, 2012. URL http://www. selenic.com/mercurial/hgrc.5.html. Joel Spolsky. Hg Init: a Mercurial tutorial, 2012a. URL http://hginit.com/. Joel Spolsky. Hg Init: Ground Up Mercurial, 2012b. URL http://hginit.com/01. html. vii 1 Orientation Mercurial is a Python-based1 distributed version control system (DVCS)2. In a DVCS anyone can obtain a complete working copy of a project (including the entire version control history), make changes to the project and publish them as a separate fork, or submit them back to the main project for merging. I am not an expert on version control software, but from what I have read (cf. Spolsky, 2012a) many people find that merging contributions from many sources is much easier in a DVCS such as Mercurial than in a centralized version control system such as CVS, RCS, or SVN. This results from how Mercurial and Git track changes—it keeps a list of changes to every file at every ‘commit’; these ‘change-sets’ are kept in a hidden (.hg) folder. 1.1 Mercurial Interfaces Mercurial is natively a command-line application which is used from a terminal on either Mac OS X or on a Linux host. It is also widely used in the ’cloud’ for collaborative sharing of code, for example at bitbucket.org. Several GUI interfaces exist for Mac (e.g. MacHg, SourceTree); TortoiseHg is very good and a highly recommended one for Window platforms that is reported to work on Linux (Buehlmann, 2013), although I have not attempted to install it on my desktop Linux computer. 1.2 File Concepts As noted above, Mercurial and Git operate by keeping track of every version of every file. You can tag a commit of a change-set at any point, to aid your ability to go back in history to examine its contents3. But, you only ever need one filename for each file. You never, ever, should need to manually create extra snapshot files within the repository—avoid the temptation to keep, e.g. file.txt, file-2013-01-07.txt, file-2013-01-07b.txt, etc. All this will do is make your list of tracked files in the directory harder to keep track of mentally (cf. Spolsky, 2012b; Noble, 2009). DCVSs were originally created for managing software, where the file contents are commonly very structured, generally with short lines (∼72 characters). When obtaining 1Python versions 2.4 through 2.7 are supported 2Another, more widely used DVCS is Git. 3Also, since Mercurial contains the entire history, you can have multiple, parallel, “sandboxes” for prototype development. But this requires a good understanding of Mercurial and keeping good track mentally of what you’re doing with all these different copies. 1 1.Orientation new changes from others or from a master project, it is possible to see the file differences with your files, on a line-by-line basis. But, DCVSs may work on any text-based file, such as a LATEX document. Hence it is key to maintain an agreed-upon standard for how lines are entered. If only editing a small portion of text, it is important to not change the formatting of entire blocks, as doing so will make a large number of unnecessary ‘diffs’ where no content has actually changed. 1.2.1 Recommendations for LATEX document text This suggests two options for .tex files: 1. Hard-wrap every line of the document to an agreed-upon line width, say 72 charac- ters, or 2. hard-wrap every sentence. It will be easier to see commit differences using (2), as a single sentence is the funda- mental ‘atom’ of a thought. This is discussed, for example, by Andrew Stacey at heading StageTwo:LineWrapping of http://www.math.ntnu.no/~stacey/HowDidIDoThat/ LaTeX/versioning.html. Similarly, the standard style rules could have special LATEX environments on single lines. It is key that your LATEX editor does not automatically hard wrap lines as you type. In Emacs this is called Auto Fill; it is called Word Wrap in Text Modes in Emacs 22 or Auto Fill in Text Modes in Emacs 24 in the menu button at top. TeXShop ‘soft’ wraps long lines at spaces between words, as the line approaches the edge of the editing window. This make editing text very readable. With Emacs 22 However earlier you can have it truncate lines longer than the window, or you can have it ‘soft’ wrap the text. However these Emacs 22 and earlier wrap text in the middle of word, with little curled arrows at the end of the visual line and start of the next line, which affects text readability when editing a document. In contrast, Emacs 24 has a new mode called ‘Word Wrap (Visual Line Mode)’. Emacs 24 is not installed system-wide on the Linux hosts, however I have installed a version on my scratch drive, for my own use. 2 / 17 058_001 2 Required Mercurial Reading I learned much about using Mercurial by installing it and playing with it on personal, stand-alone, projects, after reading several very clear introductions available online. I suggest you read these two introductions, in this order, if you have never worked with a DCVS: • Hg Init: a Mercurial tutorial, at hginit.com (Spolsky, 2012a). This cov- ers the basics, including sharing change sets, and is a good start if you have never worked with a DCVS, and progresses in this order: – Subversion Re-education (skip if you’re new to version control) – Ground up Mercurial – Setup for a Team – Fixing Goofs – Merging – Repository Architecture • Learning Mercurial in Workflows, at mercurial.selenic.com/guide/ (Buehlmann, 2012). The basic workflows include – Log keeping – Lone developer with nonlinear history – Separate features – Sharing changes while the advanced workflows include – Backing out bad revisions – Collaborative feature development – Tagging revisions – Removing history The advanced workflows can be read as you get familiar with Mercurial. After reading those, then the main Mercurial website has two links that are very useful: • Understanding Mercurial, at http://mercurial.selenic.com/wiki/UnderstandingMercurial (Buehlmann, 2012), and 3 2.Required Mercurial Reading • A Tutorial on Using Mercurial, at http://mercurial.selenic.com/wiki/Tutorial (Buehlmann, 2012). This one has ten (10) parts that include coverage of – Installation Mercurial – Initializing a repository – Cloning an existing repository – Navigating the history of a repository – Making changes to a repository, and – Sharing, Exporting, and Merging changes – Resolving failed merges. 2.1 Other Useful References You can obtain information about Mercurial from the command line, and there are many other useful references online. 2.1.1 Obtaining help If you do not remember, or want more information, about a command you can obtain help: hg: Typing hg on the command line will result in listing of 17 basic commands. hg help: Will result in a complete list of commands. hg help <command>: Will print out detailed help about the command. 2.1.2 Three reference cards I have found three reference cards online, reproduced in the following pages.