Difference between revisions of "Mercurial/Getting Started"
m (spelling, grammar) |
|||
| Line 20: | Line 20: | ||
Because multiple persons can do local commits, have different "local master copies" (somebody else could have pushed a change to the master before that alters the file you change yourself), it is impossible to refer to a specific version of a file by a version number. What is version 23 of a file? The one in your local copy, that doesn't exist on the master yet? Or version 23 of a file of another user that did commit the same file locally? | Because multiple persons can do local commits, have different "local master copies" (somebody else could have pushed a change to the master before that alters the file you change yourself), it is impossible to refer to a specific version of a file by a version number. What is version 23 of a file? The one in your local copy, that doesn't exist on the master yet? Or version 23 of a file of another user that did commit the same file locally? | ||
So instead of version numbers, specific versions are refered to using "changeset" identifiers. Think of it as checksums. | So instead of version numbers, specific versions are refered to using "changeset" identifiers. Think of it as checksums. | ||
| + | |||
| + | {{Template:Documentation/Tip| Mercurial offers the possibilities to use easier to type numeric revisions instead of changeset identifiers during work with a local repository. But remember: these numbers have no meaning outside this specific local repository. Don't use them when communicating with others.}} | ||
| + | |||
| + | == Further reading == | ||
| + | Remembering the three points above are enough to get you going. If you want to know more you'll find all things Mercurial [http://www.selenic.com/mercurial/wiki here]. An excellent tutorial can be found in "tour" chapters of the Mercurial book, which is also available [http://hgbook.red-bean.com/read/ online]. | ||
= So how to use it then (aka: What commands do I have to type?) = | = So how to use it then (aka: What commands do I have to type?) = | ||
| − | |||
| − | == | + | You want to play around with the OpenOffice.org sources without bothering with all the things a OOo domain developer needs to keep in mind? You aren't interested in this CWS thing at all? Good, this section is for you. |
| − | Creating a local copy means to clone from the master - the URL for the | + | |
| − | $ hg clone http://hg.services.openoffice.org | + | == Creating a local copy == |
| + | Creating a local copy means to clone from the master - the URL for the the main OOo development code line is http://hg.services.openoffice.org/DEV300 | ||
| + | $ hg clone http://hg.services.openoffice.org/DEV300 local_DEV300 | ||
If you know that you'll only use this as basis for different local clones and don't want it to create the actual source-files, then you can use | If you know that you'll only use this as basis for different local clones and don't want it to create the actual source-files, then you can use | ||
| − | $ hg clone -U http://hg.services.openoffice.org | + | $ hg clone -U http://hg.services.openoffice.org/DEV300 local_DEV300 |
| − | This will create a | + | This will create a treeless version, i.e. you'll get an (apparently) empty OOo-tip-repo-only directory that holds the history/changeset data only, but not the actual files. Saves some diskspace and lessens the risk of modifying the master you intended to keep pristine. |
| + | |||
| + | {{Template:Documentation/Tip| The OOo mercurial repository is quite huge, so doing cloning from the OOo server will take substantial time. A significant faster way is to download a nightly (GMT) created so called ''[http://mercurial.selenic.com/wiki/Bundle bundle]'' of DEV300 which is available [http://hg.services.openoffice.org/bundle/DEV300.hg here]. This bundle contains the full history in one highly compressed file (currently about 800MB in size). Create a treeless local DEV300 copy with | ||
| + | $ mkdir local_DEV300 | ||
| + | $ cd local_DEV300 | ||
| + | $ hg init | ||
| + | $ hg unbundle <path_to_bundle>/DEV300.hg | ||
| + | and proceed with updating it with the latest changes as described below.}} | ||
| + | |||
== updating the local copy with new changes from the master == | == updating the local copy with new changes from the master == | ||
Revision as of 13:02, 23 October 2009
Contents
This page aims to help cvs/svn users to get started with mercurial, without the need to dig in cyberspace for basic stuff. If you have a tip or general remark to share, feel free to edit the page - It's a wiki after all :-) Especially if you see something wrong here, just correct it without asking for permission on the ML
The very basics: Mercurial is a DVCS
Mercurial (hg) is a distributed version control system. This is a major difference compared to tools like CVS or subversion and that difference imposes a changed workflow compared to centralized version control systems.
Your checkout is a full repository
In a simplified view, every checkout is a full repository. You have history and version info for other branches in your local tree. So naturally such a checkout is rather big compared to a single-revision checkout done by cvs and svn. So you won't checkout a full repo every time (unless you have bandwidth to waste and too much time on your hands :-) Instead you will regularly update your local copy with the changes that were added to the repository and then "clone" (that's the term used for a "checkout") your local repository instead.
Your commits go to your local repository first
Another difference is that any change you commit will be done in your local copy only at first. You can accumulate many different commits locally and need to "push" changes to the master to finally have them in the main repo/available for everyone.
There are no version numbers anymore
Because multiple persons can do local commits, have different "local master copies" (somebody else could have pushed a change to the master before that alters the file you change yourself), it is impossible to refer to a specific version of a file by a version number. What is version 23 of a file? The one in your local copy, that doesn't exist on the master yet? Or version 23 of a file of another user that did commit the same file locally? So instead of version numbers, specific versions are refered to using "changeset" identifiers. Think of it as checksums.
Further reading
Remembering the three points above are enough to get you going. If you want to know more you'll find all things Mercurial here. An excellent tutorial can be found in "tour" chapters of the Mercurial book, which is also available online.
So how to use it then (aka: What commands do I have to type?)
You want to play around with the OpenOffice.org sources without bothering with all the things a OOo domain developer needs to keep in mind? You aren't interested in this CWS thing at all? Good, this section is for you.
Creating a local copy
Creating a local copy means to clone from the master - the URL for the the main OOo development code line is http://hg.services.openoffice.org/DEV300
$ hg clone http://hg.services.openoffice.org/DEV300 local_DEV300
If you know that you'll only use this as basis for different local clones and don't want it to create the actual source-files, then you can use
$ hg clone -U http://hg.services.openoffice.org/DEV300 local_DEV300
This will create a treeless version, i.e. you'll get an (apparently) empty OOo-tip-repo-only directory that holds the history/changeset data only, but not the actual files. Saves some diskspace and lessens the risk of modifying the master you intended to keep pristine.
updating the local copy with new changes from the master
As mentioned above, doing a full clone every time would be a waste, so how to stay up-to-date then? (Well, for working on a cws you don't need this, only when you want "HEAD" (called "tip" in Mercurial) or when you want a local copy of a master that is not available locally)
Updating means "pulling the new changes" from the master:
$ cd DEV300 # change to the directory of your main clone $ hg pull http://hg.services.openoffice.org/hg/DEV300
Caveat: While this grabs all the changes that were done on the master since the last checkout, it will *not* automatically update the source-code files on your disk. It basically only gets the history and changesets. This is of course no biggie if you use a repo-only master anyway - but if you want local source-files to reflect the newest changes, you need to do an update of your tree:
$ hg update
Since pulling the newest changes and updating to those changes is rather common, you can use the -u switch to the pull command to do both in one go:
# alternative to separate pull and update $ hg pull -u http://hg.services.openoffice.org/hg/DEV300
Note: the URL is optional in all of the above commands - if omitted, it will just use the URL that was used to clone the repo
cloning from the local repo to create a working copy
It is easier to keep a pristine copy of the sources as a base for new work, than to clean up an already modified repo, especially when you're not familiar with the tools yet :-) - so to create a working playground for your real work, clone from your local main-clone:
$ hg clone -U DEV300 target-dir # where DEV300 is your main-checkout $ hg --cwd target-dir update DEV300_m46 # same as "cd target-dir && hg update -r DEV300_m46"
This is much faster than to use "hg clone -r DEV300_m46 DEV300 target-dir" and preserves future revisions in the target-clone. It is much faster because the clone without revision uses hardlinks, creates a full-featured copy of the main-checkout very fast (plain copy). The subsequent update command (hg --cwd target-dir update DEV300_m46) creates the files that match the DEV300_m46 tag. The clone with revision creates a DEV300_m46 straight ahead, but uses a different method called "pull protocol". It needs to analyze the full history and changesets to isolate those that are included in DEV300_m46 and throws away everything that was added after DEV300_m46 and is much slower (and needs more diskspace)
