|
Size: 9070
Comment: include FAQ/TechnicalDetails
|
Size: 6670
Comment: [[Include(FAQ/Terminology)]]
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 18: | Line 18: |
| ''(the content of this section is included from the subpage ["FAQ/Terminology"])'' | |
| Line 19: | Line 20: |
| === What are revision numbers, changeset IDs, and tags? === Mercurial will generally allow you to refer to a revision in three ways: by revision number, by changeset ID, and by tag. A revision number is a simple decimal number that corresponds with the ordering of commits in the local repository. It is important to understand that this ordering can change from machine to machine due to Mercurial's distributed, decentralized architecture. This is where changeset I``Ds come in. A changeset ID is a 160-bit identifier that uniquely describes a changeset and its position in the change history, regardless of which machine it's on. This is represented to the user as a 40 digit hexadecimal number. As that tends to be unwieldy, Mercurial will accept any unambiguous substring of that number when specifying versions. It will also generally print these numbers in "short form", which is the first 12 digits. You should always use some form of changeset ID rather than the local revision number when discussing revisions with other Mercurial users as they may have different revision numbering on their system. Finally, a tag is an arbitrary string that has been assigned a correspondence to a changeset ID. This lets you refer to revisions symbolically. === What are branches, heads, and the tip? === The central concept of Mercurial is branching. A 'branch' is simply an independent line of development. In most other version control systems, all users generally commit to the same line of development called 'the trunk' or 'the main branch'. In Mercurial, every developer effectively works on a private branch and there is no internal concept of 'the main branch'. Thus Mercurial works hard to make repeated merging between branches easy. Simply run {{{hg pull}}}, {{{hg merge}}} and commit the result. 'Heads' are simply the most recent commits on a branch. Technically, they are changesets which have no children. Merging is the process of joining points on two branches into one, usually at their current heads. Use "hg heads" to find the heads in the current repository. The 'tip' is the most recently changed head, and also the highest numbered revision. If you have just made a commit, that commit will be the tip. Alternately, if you have just pulled from another repository, the tip of that repository becomes the current tip. The 'tip' is the default revision for many commands such as update, and also functions as a special symbolic tag. |
[[Include(FAQ/Terminology)]] |
(see also TipsAndTricks)
Mercurial Frequently Asked Questions
1. General Questions
1.1. What is the license of the project?
The project is available under the GNU General Public License, v2. See COPYING in the release for more details.
2. Common Problems
(the content of this section is included from the subpage ["FAQ/CommonProblems"])
3. Terminology
(the content of this section is included from the subpage ["FAQ/Terminology"])
4. General Usage
4.1. How does merging work?
The merge process is simple. Usually you will want to merge the tip into your working directory. Thus you run hg merge and Mercurial will incorporate the changes from tip into your local changes.
The first step of this process is tracing back through the history of changesets and finding the 'common ancestor' of the two versions that are being merged. This is done on a project-wide and a file by file basis.
For files that have been changed in both projects, a three-way merge is attempted to add the changes made remotely into the changes made locally. If there are conflicts between these changes, the user is prompted to interactively resolve them.
Mercurial uses a helper tool for this, which is usually found by the hgmerge script. Example tools include tkdiff, kdiff3, and the classic RCS merge.
After you've completed the merge and you're satisfied that the results are correct, it's a good idea to commit your changes. Mercurial won't allow you to perform another merge until you've done this commit as that would lose important history that will be needed for future merges.
4.2. What are some best practices for distributed development with Mercurial?
First, merge often! This makes merging easier for everyone and you find out about conflicts (which are often rooted in incompatible design decisions) earlier.
Second, don't hesitate to use multiple trees locally. Mercurial makes this fast and light-weight. Typical usage is to have an incoming tree, an outgoing tree, and a separate tree for each area being worked on.
The incoming tree is best maintained as a pristine copy of the upstream repository. This works as a cache so that you don't have to pull multiple copies over the network. No need to check files out here as you won't be changing them.
The outgoing tree contains all the changes you intend for merge into upsteam. Publish this tree with hg serve or hgweb.cgi or use hg push to push it to another publicly availabe repository.
Then, for each feature you work on, create a new tree. Commit early and commit often, merge with incoming regularly, and once you're satisfied with your feature, pull the changes into your outgoing tree.
4.3. How do I import from a repository created in a different SCM?
See ConvertingRepositories for various tips.
4.4. What about Windows support?
See WindowsInstall for getting started using Windows.
4.5. Is there a GUI front-end?
See ["GUIClients"] for information on graphical merge tools and other front-ends.
5. Tags
5.1. How do tags work in Mercurial?
Tags work slightly differently in Mercurial than most revision systems. The design attempts to meet the following requirements:
- be version controlled and mergeable just like any other file
- allow signing of tags
- allow adding a tag to an already committed changeset
- allow changing tags in the future
Thus Mercurial stores tags as a file in the working dir. This file is called .hgtags and consists of a list of changeset IDs and their corresponding tags. To add a tag to the system, simply add a line to this file and then commit it for it to take effect. The hg tag command will do this for you and hg tags will show the currently effective tags.
Note that because tags refer to changeset IDs and the changeset ID is effectively the sum of all the contents of the repository for that change, it is impossible in Mercurial to simultaneously commit and add a tag. Thus tagging a revision must be done as a second step.
5.2. What if I want to just keep local tags?
You can use "hg tag" command with an option -l or --local. This will store the tag in the file .hg/localtags, which will not be distributed or versioned. The format of this file is identical to the one of .hgtags and the tags stored there are handled the same.
5.3. How do tags work with multiple heads?
The tags that are in effect at any given time are the tags specified in each head, with heads closer to the tip taking precedence. Local tags override all other tags.
5.4. What if multiple lines with different revisions use the same tag name in .hgtags?
Only the last line where the tag appears is taken into account. The behavior is identical when this happens in .hg/localtags.
6. Bugs and Features
6.1. I found a bug, what do I do?
Report it to the mercurial mailing list, mercurial@selenic.com or in the bug tracker http://www.selenic.com/mercurial/bts/
6.2. What should I include in my bug report?
Enough information to reproduce or diagnose the bug. If you can, try using the hg -v and hg -d switches to figure out exactly what Mercurial is doing.
If you can reproduce the bug in a simple repository, that is very helpful. The best is to create a simple shell script to automate this process, which can then be added to our test suite.
6.3. Can Mercurial do <x>?
If you'd like to request a feature, send your request to mercurial@selenic.com. As Mercurial is still very new, there are certainly features it is missing and you can give us feedback on how best to implement them.
Be sure to see ToDo and MissingFeatures to see what's already planned and where we need help.
7. Web Interface
7.1. How do I link to the latest revision of a file?
Find the URL for the file and then replace the changeset identifier with tip.
7.2. How do I change the style of the web interface to the visually more attractive gitweb?
In [http://www.selenic.com/mercurial/hgrc.5.html hgrc] set
[web] style = gitweb
To switch back to the default style specify "style = default" (see [http://hgbook.red-bean.com/hgbookch6.html#x10-1390006.6.5 hgbook]).
8. Technical Details
(the content of this section is included from the subpage ["FAQ/TechnicalDetails"])
9. Mercurial Book
See ["/MercurialBook"].