Instant Mercurial Distributed SCM Essentials How-to [Instant] — Save 50%
A series of 10 easy-to-perform practical recipes to quick start and get going with Mercurial simplicity and power with this book and ebook
This article by Christophe Muller, from the book Instant Mercurial SCM Essential How-to, explains how to work with local files, either personal projects or files you wish to be version controlled (for example, source code or configuration files). You will learn how to create a new repository, make changes, and track them (selecting files to track, recording changes, and reversing those changes).
(For more resources related to this topic, see here.)
Now that you have Mercurial set up on your computer, you are going to use it to track all the changes that can happen in a configuration directory, for example, in the configuration files of Apache2 (a web server). It could of course be used in any other type of directory and files: your home directory configuration files, some personal development projects, or some Mozilla Firefox configuration files such as user.js and prefs.js, and likewise. If you do not have Apache2 installed on your computer, you can do the same type of exercises, for instance, in $HOME/src. Also, with the owners of the /etc/apache2 files being root, you will need to change their owner to your account. For example, your username/group both being mary/mary:
$ sudo chown -R mary:mary /etc/apache2/
How to do it...
- The first thing to do is to initialize a new repository by typing these lines:
$ cd /etc/apache2/
$ hg init
- You can then show the status of the files in your new repository, that is, which files are tracked and which are unknown to Mercurial, and also which files have changed, which have been deleted, and so on. This is done using the Mercurial status command:
$ hg status
- As you can see, everything is untracked right now. The way to tell Mercurial which files you want to be version controlled and added to your newly created repository is by using the add command. For example, if you want to track changes in the apache2.conf file, and all the files of the sites-available directory, you need to type:
$ hg add apache2.conf sites-available/
- Showing the status again, Mercurial now tells us that three files have been added (by showing A, which denotes Added ; instead of ?—, denoting Unknown , in front of its path):
$ hg status
- Now if you want to record the initial version of these files (the one provided by your distribution), you need to use the commit command and add a log message using the -m option:
$ hg commit -m"initial version"
- Using the log command, you can print the entire history of your repository (here you used commit only once, so only one change—called a changeset —is listed):
$ hg log
user: Mary <email@example.com> […date…]
summary: initial version
- Whenever you change a file, you can record the modification in Mercurial with the commit command. Let's type the following sequence using the status, diff, commit, and log commands:
$ vi apache2.conf
..make some changes: add "# new line" at the end of the file
$ hg status -m
$ hg diff
diff -r 7b3b5fcb16d0 apache2.conf
+# new line
$ hg commit -m"added a line at the end"
$ hg log
user: Mary <firstname.lastname@example.org>
summary: added a line at the end
changeset: 0:7b3b5fcb16d0 […]
- You can also reverse the modifications; for instance, if you modify a line again in apache2.conf, such as changing # new line by # new linez, using the diff command, you can see your modification:
$ hg diff
diff -r b0d2bfb95d81 apache2.conf […]
-# new line
+# new linez
- It is then possible to come back to the latest saved version using the revert command:
$ hg revert apache2.conf
$ hg status
$ tail -1 apache2.conf
# new line
- At this stage, you can't see the M apache2.conf file any more, and the value at the last line is the one that is not modified, but there is a new file called apache2.conf.orig; this is because the revert command saves your modifications in a backup file. You can either delete it afterward or you can use the --no-backup option if you know what you do. Mercurial has a conservative philosophy to avoid losing data.
- Finally, if you realize that you do not need a file any more, you can remove it from being version controlled and from your working directory by using the remove command. For example, if you don't need the SSL configuration file of Apache, you can remove it by typing:
$ hg remove sites-available/default-ssl
$ hg status
Instant Mercurial Distributed SCM Essential How-to
$ hg commit -m"removed unused ssl conf file"
$ ls sites-available/
- Note that the file has disappeared from your working directory, and even if you create a file with the same name, it will not be version controlled anymore (unless you add it again). But, of course, it is still possible to get it back or to get a version of apache2.conf exactly how it came with the distribution. In order to do that, you need to use the update command and ask to switch to revision 0:
$ hg update -C 0
$ ls sites-available/
$ tail -1 apache2.conf
- In order to switch back to the latest revision (it is coined the tip), you can just call update again with no revision passed as an argument:
$ hg update -C
2 files updated, 0 files merged, 1 files removed, 0 files
How it works...
With this sequence, you already know how to manage versions of your personal projects: save a version, undo a change, retrieve an older version, and so on. Let's take a closer look at what happens under the hood.
After you type hg init, a directory called .hg is created:
$ ls -a
. apache2.conf envvars magic mods-enabled sites-availabl
.. conf.d .hg mods-available ports.conf sites-
This directory, called a repository, contains the history of your project and some Mercurial metadata. This is where Mercurial records all your revisions of tracked files (actually, it stores only the differences between each revision, like RCS/CVS/Subversion, and in compressed form, so the size is usually less than that of the the actual data!). And also, this is where it stores the commit messages, information about branches, tags, bookmarks, and so on. All the other files and directories beside .hg are your project files; they form what is called a working directory. If ever you would like to forget version control in this zone, you can just remove the .hg directory.
Another interesting thing to note is that, contrary to Subversion for instance, in a local .hg repository, you do not have less information than in a repository in a central server! Your installation of Mercurial actually allows you to have both a client command (or GUI), with which you can work locally or with distant servers, and a server, with which you can share your work with colleagues. This is because, with DVCS ( Distributed VCS ), there is no difference between the data checked out to work with and the data ready to be published. When you either create a local repository or clone an existing one from a server, you have all the necessary information (in the .hg directory) to become a publisher yourself.
This section will discuss supplementary commands or options.
First of all, Mercurial has many commands (the list of which you can get with the command hg help); in addition to adding and removing files from being version controlled, you can also use the copy command to copy a file into a new file, and similarly, you have a rename command. The difference between the OS file copy and the one that Mercurial has is that when you receive a change made by somebody else to the original file, it will also be applied by Mercurial to the new file; but for this magic to work, you have to tell Mercurial about the copies/renames so it can track them. There are also convenient commands, such as addremove, which allows you to automatically add all new files and remove (from version control) files that have been deleted.
Please refer to the built-in help system or to reference documentation, such as Mercurial: The Definitive Guide, available online at o http://hgbook.red-bean.com/, to get the complete list of options for each command. You have seen -m (or --message) in the commit command to specify a log message; if you omit this option, Mercurial will prompt you to get a message using $EDITOR. Also, you have seen -C (or --clean) in the update command; it will tell Mercurial to discard uncommitted changes when switching to another version (otherwise, local changes would automatically be merged into the requested version).
This article explained how to work with local files, either personal projects or files that you wanted to be version controlled (for example, source code or configuration files). You also learned how to create a new repository, make changes, and track them (selecting files to track, recording changes, and reversing those changes).
Resources for Article :
- Apache Continuum: Ensuring the Health of your Source Code (Part 1) [Article]
- Apache Continuum: Ensuring the Health of your Source Code (Part 2) [Article]
- Negotiation Strategy for Effective Implementation of COTS Software [Article]
About the Author :
Christophe Muller has been working in the software industry for more than two decades. He is currently responsible for the software development tools at Wyplay, a software development company specializing in TV-centric software, where he is in charge of setting up tools and common software practices for more than 80 developers transitioning to Scrum.
He started working at Simulog on several ESPRIT research projects with a queuing network language and a performance evaluation environment. He then worked in the smart card industry on the design of an object-oriented framework for using smart cards as well as a next generation Java OS for smart-card-like devices. As a member of the Gemplus Research Lab, he published several articles and, as a speaker, participated in conferences on smart cards such as the Gemplus Developer Conference, CardTech/SecurTech, Cartes, and JavaOne. He has always been passionate about sharing his knowledge and experience through training, setting up knowledge-sharing tools, and supporting teams. He has given courses in queuing networks and performance evaluation, the Tcl/Tk language and toolkit, shell scripting, Unix tools, such as Emacs, GNU Make, and Awk, and version control tools, such as RCS, CVS, Subversion, and Mercurial.
He graduated as a computer science engineer from ENSERB (École Nationale d'Électroniqueet de Radioélectricité de Bordeaux), France, he has a DEA (five-year degree after high-school graduation) in AI for Manufacturing Systems from the GRAI Laboratory in Bordeaux, and he has a Master's degree in Software Engineering from CERICS.
He is married and has two children. He currently lives in the south of France.