Hg Init: Part 2. The Basics of Mercurial

This is the second part of the Hg Init Series : A Mercurial Study Guide by Joel Spolsky . You may also want to read the first part, “Re-education for Subversion Users . ”

Even if you are working alone, you should use Mercurial. So you can get all the delights of version control. This part will show how easy it is to add a directory to Mercurial to easily track down previous versions.

Part 2. Mercurial Basics

')
Mercurial is a version control system . Developers use it to administer source code. She has two main purposes:

1. It stores all previous versions of each file.
2. It can merge different versions of your code, that is, employees can independently work on the code and then merge their changes.

Without Mercurial, you could try to keep previous versions by simply creating many copies of the directory with code:



It is a chore, requires a lot of disk space and creates confusion. Better to use a version control system.

Most people work with Mercurial through the command line interface. So you can work on Windows, Unix, and Mac. The command for Mercurial is hg :



If you run hg without parameters, you will get a list of the most frequently used commands. You can also try hg help for a complete list of commands.

In order to take advantage of version control, you need a repository . The repository stores all previous versions of all your files. In fact, to save disk space, all previous versions will not be stored - only a compact list of changes will be stored.

In the old days, getting a repository was a big deal. You needed to have a central server and you had to install software on it. Mercurial is a distributed system, so you can use it without a fancy central server. You can use Mercurial using your computer alone. And getting a repository is super easy: you just go to the directory with your code ...



... and run the hg init command:

hg init
creates a repository.

Wait a minute, did something happen? It looks like nothing has changed. No, if you look better, you will see that a new .hg directory has .hg :



This is the repository! This is a directory with everything Mercurial needs to work. Settings, previous versions of files, tags, an extra pair of socks in case of rain, and so on. Do not climb there. You almost always don't have to mess with this directory yourself.

Well, well, since we now have a freshly baked repository, then we will want to add all the source files to it. This is also simple: you just need to do hg add .

hg add
marks files as scheduled to be added to the repository. Files will not actually be added until you commit the changes.

There is one more step left ... you need to commit your changes . Which changes? The fact of adding all these files.

Why do you have to commit changes? When working with Mercurial, recording changes means: “Hey, this is how the files look now, so please remember them.” It's like making a copy of the entire directory ... every time you have something changed and you like it, you commit changes.

hg commit
saves the current state of all files in the repository.

Mercurial will launch an editor so that you can type a comment for the changes. You just need to write something that reminds you of the changes made.



After you save and exit the editor, your changes will be recorded.

You can run hg log to view the change history. This is like a blog for your repository:

hg log
displays the history of changes recorded in the repository.

Let's change the file and see what happens.



Since we made the change, we can fix it with hg commit :



Note that Mercurial guessed that only one file, a.txt, was changed:



And now, after I committed (fixed the changes), let's look at the story:



Like any current blogger, Mercurial puts the newest in the beginning.

I'm going to make another change, just to amuse myself.



Kommichu (commit changes):



My message to the commit:



And what about our history now?



Well, that was fun. I made a few changes and each time, making a significant change, I fixed it in the repository.

I know you are thinking now: "JOEL, ALL THIS IS LOOKING FOR EMPTY TIME TIME." Why all this confusion with commits?

Patience, my young friend. You are about to learn how to capitalize on all of this.

For a start: let's say you made a big mistake in the editing process.



And then, God, in addition to everything, you deleted a couple of very important files.



At a time when there was no Mercurial, all this could be a good reason to go to the system administrator. There, with tears in his eyes, you would ask him a piercingly sad question: "Why is the backup system" temporarily "not working all the past eight months."

The system administrator, whom everyone calls Taco , is too modest and does not have lunch with the rest of the team. In those rare cases when he does not sit in his wheelchair, you can see a triangular salsa- colored spot where you fell, flying between your legs, drops from his Mexican snacks. These drops guarantee that no one will take his chair, although this is one of the excellent chairs from Herman Miller , bought by the founders of the company for themselves, and not the usual budget office something, because of which everyone has a backache.

In any case, there is no backup, yeah.

Thanks to Mercurial, if you don’t like what you’ve done, you can execute the convenient hg revert command, which immediately returns your directory to the view it was in at the time of the last commit.

hg revert
returns the modified files to the form fixed in the repository.

I used the argument --all , because I wanted to return all files to the previous state.

Thus, when you work on source code using Mercurial, you:

1. Make changes
2. Evaluate if they are suitable
3. If suitable, then commit
4. If not suitable, then perform revert
5. GOTO 1

(I know. I use the command line, on Windows, and also the GOTO operator — I am the strongest programmer I've ever lived.)

Over time, you can forget where you left off and what you have changed since the last commit. Mercurial keeps track of all this for you. All you need to do is execute hg status and Mercurial will give you a list of changed files.

hg status
displays a list of changed files.

Suppose I created one file, edited another, and deleted a third one.



hg status displays a list of changed files, adding an icon at the beginning of each line. This icon indicates what happened. “M” means “Modified” - the file has been modified. "!" means no - the file should be here, but somewhere gone. "?" means that the state is undefined - Mercurial knows nothing about this file. Don't know yet.

Let's deal with the changes one by one. Here is what has changed in the a.txt file? You can forget what changed. Damn, I hardly remember what I usually eat for breakfast. And it is especially anxious that these are always crisp ringlets of CHEERIOS . In any case, a.txt is modified. What has changed?

And there is a command for this: hg diff will tell you exactly what happened to the file from the last commit.

hg diff
shows what has changed in the file.

The format of the result is a little confusing, but the most important thing is that you can see lines starting with a minus (this is what was deleted) and lines that start with a plus (this is what has been added). So you can see that “Normal people” was replaced by “Civilians”.

Now about that missing favicon.ico file. As already mentioned, if you really did not plan to delete it, you can issue the hg revert command to restore it. But suppose you actually wanted to remove it. Each time you delete (or add) a file, you must report this event to Mercurial.

hg remove
marks files as scheduled for removal from the repository. Files on the disk will not be deleted until you commit the changes.

"R" means "Removed", that is, marked for deletion. Mercurial will delete this file during the next commit. ( The history for this file is saved in the repository, so, of course, we can always get it back.) And finally, we need to add this new b.txt file:



“A” means “Added,” that is, marked for addition. Notice that I spilled to write hg status every time? For Mercurial, a minimum set of letters that uniquely defines a command is sufficient, and only one command begins on st .

Having dealt with the questions and exclamation marks, I can continue and make changes:



What else you should pay attention to in the hg log output: the changeset line displays the number of each commit. In fact, even two numbers: a short, convenient, like “0” for the first revision and a long incomprehensible hexadecimal, which you can ignore for now.

Remember, Mercurial stores enough information in the repository to recreate any version of any file.

First of all, with the help of a simple hg cat you can output the contents of any version of any file to the console. For example, here’s how to see what is now in the a.txt file:

hg cat
displays the contents of any file for any revision.

In order to see how the file looked before, I can simply specify the desired changeset number (changeset from the log) using the argument -r ("revision", that is, revision):



If a file has complex content or a large length, and it has changed only a little, then I can use the hg diff with the argument r to display the difference between the two revisions. For example, here’s how to see the difference between revisions 0 and 1:



And finally - I hope that you have not yet collapsed due to fatigue - before I finish this part, I want to show you another little thing : with the help of the hg update command you can move back and forth by the time you create any revision. Well, in fact , you will not be able to move to the future, although it would be super cool, yes. With only four revisions, you could run hg update -r 103994 and get a really cool version of your sources. With gravitas and other futuristic things. But of course this is not possible.

What is actually possible is to return to any revision. Watch your hands:

hg update
brings the working directory to a state like a given revision.

In fact, to move back and forth between revisions, hg update makes the memorized changes to the files. If a file has been added or deleted, this command adds or deletes it on the disk. Running hg update without additional parameters brings the working directory to the state of the latest revision.

check yourself

Fine! This part is complete. Here is all that you should be able to do at the moment:

1. Create repository
2. Add or remove files from repository
3. After making changes, review what was done and then
4. ... commit changes if you like them
5. ... or roll back changes if you don’t like
6. View previous versions of files or bring the working directory to the state of a revision.

Continued here:
Hg Init: Part 3. We get used to working in a team