|
Size: 5409
Comment:
|
Size: 7389
Comment: converted to 1.6 markup
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| = Mercurial for CVS users = | = CVS Concepts = (!) ''The structure of this topic is borrowed from the [[http://svnbook.red-bean.com/en/1.1/svn-book.html#svn-ap-a|Subversion Book]]. Thanks, guys!'' |
| Line 3: | Line 4: |
| (The structure of this topic is borrowed from the [http://svnbook.red-bean.com/en/1.1/svn-book.html#svn-ap-a Subversion Book]. Thanks, guys!) | <<TableOfContents(3)>> |
| Line 5: | Line 6: |
| * {anchorlink: convert Converting a CVS repository} * {anchorlink: rev Revisions} * {anchorlink: disconnect Disconnected operation} * {anchorlink: tag Modules, branching and tagging} * {anchorlink: collab Collaborating with other people} ** {anchorlink: server Running a server} * {anchorlink: watch Watching files} * {anchorlink: binary Binary files} * {anchorlink: keyword Keywords expansion} |
<<Anchor(workflow)>> == Workflow in Mercurial compared to CVS == The main mental difficulty when switching form CVS to Mercurial lies in the slightly different workflow. In Mercurial the golden rule is: if you completed a piece of work, check in, regardless of other people. |
| Line 15: | Line 10: |
| == {anchor: convert} Converting a CVS repository == | With '''CVS''', before committing you '''first pull''' in remote changes (cvs up) and merge before checking in. this of course risks that you might lose some work, it does not work as expected, etc. |
| Line 17: | Line 12: |
| For details of how to convert a ["CVS"] repository to a ["Mercurial"] ["Repository"], see ConvertingRepositories. | With '''Mercurial''' you '''first do a checkin''' in your local repository. Afterwards you pull in remote changes, in many cases Mercurial then creates a second head. one contains your changes, one the other people's changes. If you want to keep your head, do "hg merge other-head". Then you commit to the remote server (see Collaboration below for how to get it there). The checkin first policy allows for much more security, you can easily go back to your original version before you started with pulling in changes. |
| Line 19: | Line 14: |
| == {anchor: rev} Revisions == | There is one point you have to pay attention when using this workflow: you need to have a tool which manages binary merge. On Windows, Joachim Eibl's kdiff3 new version ships a version qt4 version called "kdiff3-QT4.exe" which recognizes binary files. Pressing "cancel" and "do not save" leaves you with the version of the file you have currently in the filesystem. See TipsAndTricks and BinaryFiles for details. |
| Line 21: | Line 16: |
| In CVS, revision numbers describe the history of individual files. In ["Mercurial"], ["RevisionNumber"]s describe the history of an entire ["Repository"]. Furthermore, in ["Mercurial"], a RevisionNumber is /local/ to a repository. To uniquely identify a ChangeSet, use a ChangeSetID. | <<Anchor(convert)>> == Converting a CVS repository == |
| Line 23: | Line 19: |
| == {anchor: disconnect} Disconnected operation == | For details of how to convert a [[CVS]] repository to a [[Mercurial]] [[Repository]], see ConvertingRepositories. |
| Line 25: | Line 21: |
| ["CVS"] requires that you have access to the central repository in order to perform any operation other than a simple text edit. By contrast, a ["Repository"] in ["Mercurial"] is a self-contained entity that contains the complete history of all files in the repository. You do not need to be connected to any server in order to perform any operation. You can even share your changes with others using USB memory sticks. | <<Anchor(rev)>> == Revisions == |
| Line 27: | Line 24: |
| == {anchor: tag} Modules, branching and tagging == | In CVS, revision numbers describe the history of individual files. In [[Mercurial]], [[RevisionNumber]]s describe the history of an entire [[Repository]]. Furthermore, in [[Mercurial]], a RevisionNumber is ''local'' to a repository. To uniquely identify a ChangeSet, use a [[ChangeSetID]]. |
| Line 29: | Line 26: |
| ["CVS"] has a very confused and confusing notion of modules, branching and tagging. I won't even attempt to describe these ideas. | <<Anchor(disconnect)>> == Disconnected operation == [[CVS]] requires that you have access to the central repository in order to perform any operation other than a simple text edit. By contrast, a [[Repository]] in [[Mercurial]] is a self-contained entity that contains the complete history of all files in the repository. You do not need to be connected to any server in order to perform any operation. You can even share your changes with others using USB memory sticks. <<Anchor(tag)>> == Modules, branching and tagging == [[CVS]] has a very confused and confusing notion of modules, branching and tagging. I won't even attempt to describe these ideas. |
| Line 34: | Line 41: |
| In ["Mercurial"], a branch is a repository. Nothing more or less. A repository is a branch. Repeat the soothing mantra. | When working with [[Mercurial]], you'll find the word "branch" used for what may seem like two different concepts. The commands used for both are also different, but they both point to the same paradigm of SCM, and so are both about branching. |
| Line 36: | Line 43: |
| The /verb/ "to branch" simply means "to make a clone of a repository at a particular revision". | ==== Branching by Cloning ==== |
| Line 38: | Line 45: |
| If every repository is a branch, how do you keep track of which one is which? That's simply a matter of convention. ["Mercurial"] has no idea which ["Repository"] is the "trunk", or which is a "branch"; it's all a matter of how you use the repositories. See WorkingPractices and CvsLikePractice for some suggestions. | In [[Mercurial]], a branch is a repository. Nothing more or less. A repository is a branch. Repeat the soothing mantra. The ''verb'' "to branch" simply means "to make a clone of a repository at a particular revision". If every repository is a branch, how do you keep track of which one is which? That's simply a matter of convention. [[Mercurial]] has no idea which [[Repository]] is the "trunk", or which is a "branch"; it's all a matter of how you use the repositories. See WorkingPractices and CvsLikePractice for some suggestions. ==== Branching inside a repository ==== This definition of branching is covered at [[Branch]] |
| Line 42: | Line 57: |
| A Mercurial ["Tag"] is just a symbolic name for a ChangeSet. See ["Tag"] for a little more discussion. | A Mercurial [[Tag]] is just a symbolic name for a ChangeSet. See [[Tag]] for a little more discussion. |
| Line 46: | Line 61: |
| In ["CVS"], a module is a collection of directories that you can check out under one name. | In [[CVS]], a module is a collection of directories that you can check out under one name. |
| Line 48: | Line 63: |
| The equivalent Mercurial concept is the ["Repository"], but there's no notion in Mercurial of "bundling" repositories together in the way that CVS bundles modules under the ''CVSROOT'' directory. | The equivalent Mercurial concept is the [[Repository]], but there's no notion in Mercurial of "bundling" repositories together in the way that CVS bundles modules under the {{{CVSROOT}}} directory. |
| Line 50: | Line 65: |
| == {anchor: collab} Collaborating with other people == | <<Anchor(collab)>> == Collaborating with other people == |
| Line 52: | Line 68: |
| With CVS, the standard way to share changes with other people is simply to check them in. Some projects have a convention of posting UnifiedDiff patches to a mailing list /before/ making a checkin. | While in CVS you get a copy of the files onto your disk, in Mercurial you get a complete repository and the files on your disk. |
| Line 54: | Line 70: |
| In ["Mercurial"], collaboration is much more flexible. You can share changes in any number of ways, including (but not limited to) the following: | With CVS, the standard way to share changes with other people is simply to check them in. Some projects have a convention of posting UnifiedDiff patches to a mailing list ''before'' making a checkin. |
| Line 56: | Line 72: |
| * ["Export"] one or more ["ChangeSet"]s and ** put the exported ["PatchFile"]s on a server for someone to download ** email the ["PatchFile"]s to a maintainer or mailing list ** copy the ["PatchFile"]s onto a memory stick and give them to someone else * ["Push"] (or rsync) the ["ChangeSet"]s into a ["Repository"] from which other people can ["Pull"] them * ["Clone"] a copy of the ["Repository"] onto a CD-ROM and hand it to someone else |
In [[Mercurial]], collaboration is much more flexible. You can share changes in any number of ways, including (but not limited to) the following: |
| Line 63: | Line 74: |
| == {anchor: server} Running a server == | * [[Export]] one or more [[ChangeSet]]s and * put the exported [[PatchFile]]s on a server for someone to download * email the [[PatchFile]]s to a maintainer or mailing list * copy the [[PatchFile]]s onto a memory stick and give them to someone else * [[Push]] (or rsync) the [[ChangeSet]]s into a [[Repository]] from which other people can [[Pull]] them * [[Clone]] a copy of the [[Repository]] onto a CD-ROM and hand it to someone else |
| Line 65: | Line 81: |
| With ["CVS"], the common way to manage a server is to provide anonymous access using the ''pserver'' command, and authenticated access over ''ssh''. | <<Anchor(server)>> == Running a server == With [[CVS]], the common way to manage a server is to provide anonymous access using the {{{pserver}}} command, and authenticated access over {{{ssh}}}. |
| Line 69: | Line 88: |
| In ["Mercurial"], you can provide anonymous access using HTTP. You can do this either with a CGI script (see the ''hgweb.cgi'' script in the distribution) or by running a dedicated server (using the ''hg serve'' command). | In [[Mercurial]], you can provide anonymous access using HTTP. You can do this either with a CGI script (see the {{{hgweb.cgi}}} script in the distribution) or by running a dedicated server (using the {{{hg serve}}} command). |
| Line 75: | Line 94: |
| Mercurial allows authenticated access to repositories, by tunnelling using the ''ssh'' command. To perform an operation over ''ssh'', compatible versions of Mercurial must be installed on both the local and remote sides, and available through your shell's search path on the remote side. | Mercurial allows authenticated access to repositories, by tunnelling using the {{{ssh}}} command. To perform an operation over {{{ssh}}}, compatible versions of Mercurial must be installed on both the local and remote sides, and available through your shell's search path on the remote side. |
| Line 77: | Line 96: |
| == {anchor: watch} Watching files == | <<Anchor(watch)>> == Watching files == |
| Line 79: | Line 99: |
| ["CVS"] lets you "put a watch" on files, which requires that other developers run ''cvs edit'' before they can edit a file. ["Mercurial"] has no corresponding concept, since a Mercurial ["Repository"] is a single-user entity that is not "connected" to any other. | [[CVS]] lets you "put a watch" on files, which requires that other developers run {{{cvs edit}}} before they can edit a file. [[Mercurial]] has no corresponding concept, since a Mercurial [[Repository]] is a single-user entity that is not "connected" to any other. |
| Line 81: | Line 101: |
| == {anchor: binary} Binary files == | <<Anchor(binary)>> == Binary files == |
| Line 83: | Line 104: |
| The delta algorithm used by ["Mercurial"] handles text and binary files equally well, this meaning that only the differences between revisions are stored. On the other hand, ["CVS"] was designed to work with ASCII text, and stores a full copy of each binary file version, with the consequent waste of space. | The delta algorithm used by [[Mercurial]] handles text and binary files equally well, this meaning that only the differences between revisions are stored. On the other hand, [[CVS]] was designed to work with ASCII text, and handles binary files as if they were text (i.e., treating the contents as lines separated by LF characters, and storing line-by-line deltas between revisions). For most binary files, this is very wasteful. |
| Line 85: | Line 106: |
| == {anchor: keyword} Keywords expansion == | See [[#workflow|workflow]] paragraph for remaining difficulties in using BinaryFiles with mercurial. |
| Line 87: | Line 108: |
| ["CVS"] expands keywords such as $Revision: 1.12 $ by adding information from it. | <<Anchor(keyword)>> == Keywords expansion == [[CVS]] expands keywords such as $Revision: 1.12 $ by adding information from it. This feature is not in [[Mercurial]] - see http://www.selenic.com/pipermail/mercurial/2005-August/003887.html, [[KeywordPlan]], [[KeywordExtension]]. |
CVS Concepts
The structure of this topic is borrowed from the Subversion Book. Thanks, guys!
Contents
1. Workflow in Mercurial compared to CVS
The main mental difficulty when switching form CVS to Mercurial lies in the slightly different workflow. In Mercurial the golden rule is: if you completed a piece of work, check in, regardless of other people.
With CVS, before committing you first pull in remote changes (cvs up) and merge before checking in. this of course risks that you might lose some work, it does not work as expected, etc.
With Mercurial you first do a checkin in your local repository. Afterwards you pull in remote changes, in many cases Mercurial then creates a second head. one contains your changes, one the other people's changes. If you want to keep your head, do "hg merge other-head". Then you commit to the remote server (see Collaboration below for how to get it there). The checkin first policy allows for much more security, you can easily go back to your original version before you started with pulling in changes.
There is one point you have to pay attention when using this workflow: you need to have a tool which manages binary merge. On Windows, Joachim Eibl's kdiff3 new version ships a version qt4 version called "kdiff3-QT4.exe" which recognizes binary files. Pressing "cancel" and "do not save" leaves you with the version of the file you have currently in the filesystem. See TipsAndTricks and BinaryFiles for details.
2. Converting a CVS repository
For details of how to convert a CVS repository to a Mercurial Repository, see ConvertingRepositories.
3. Revisions
In CVS, revision numbers describe the history of individual files. In Mercurial, RevisionNumbers describe the history of an entire Repository. Furthermore, in Mercurial, a RevisionNumber is local to a repository. To uniquely identify a ChangeSet, use a ChangeSetID.
4. Disconnected operation
CVS requires that you have access to the central repository in order to perform any operation other than a simple text edit.
By contrast, a Repository in Mercurial is a self-contained entity that contains the complete history of all files in the repository. You do not need to be connected to any server in order to perform any operation. You can even share your changes with others using USB memory sticks.
5. Modules, branching and tagging
CVS has a very confused and confusing notion of modules, branching and tagging. I won't even attempt to describe these ideas. Pretend you never heard about any of it.
5.1. Branches
When working with Mercurial, you'll find the word "branch" used for what may seem like two different concepts. The commands used for both are also different, but they both point to the same paradigm of SCM, and so are both about branching.
5.1.1. Branching by Cloning
In Mercurial, a branch is a repository. Nothing more or less. A repository is a branch. Repeat the soothing mantra.
The verb "to branch" simply means "to make a clone of a repository at a particular revision".
If every repository is a branch, how do you keep track of which one is which? That's simply a matter of convention. Mercurial has no idea which Repository is the "trunk", or which is a "branch"; it's all a matter of how you use the repositories. See WorkingPractices and CvsLikePractice for some suggestions.
5.1.2. Branching inside a repository
This definition of branching is covered at Branch
5.2. Tags
A Mercurial Tag is just a symbolic name for a ChangeSet. See Tag for a little more discussion.
5.3. Modules
In CVS, a module is a collection of directories that you can check out under one name.
The equivalent Mercurial concept is the Repository, but there's no notion in Mercurial of "bundling" repositories together in the way that CVS bundles modules under the CVSROOT directory.
6. Collaborating with other people
While in CVS you get a copy of the files onto your disk, in Mercurial you get a complete repository and the files on your disk.
With CVS, the standard way to share changes with other people is simply to check them in. Some projects have a convention of posting UnifiedDiff patches to a mailing list before making a checkin.
In Mercurial, collaboration is much more flexible. You can share changes in any number of ways, including (but not limited to) the following:
Push (or rsync) the ChangeSets into a Repository from which other people can Pull them
Clone a copy of the Repository onto a CD-ROM and hand it to someone else
7. Running a server
With CVS, the common way to manage a server is to provide anonymous access using the pserver command, and authenticated access over ssh.
7.1. Anonymous access
In Mercurial, you can provide anonymous access using HTTP. You can do this either with a CGI script (see the hgweb.cgi script in the distribution) or by running a dedicated server (using the hg serve command).
Mercurial's HTTP server provides no access controls, so anyone who can connect to your web server can clone any repositories you publish, unless you take steps to secure them in some way.
7.2. Authenticated access
Mercurial allows authenticated access to repositories, by tunnelling using the ssh command. To perform an operation over ssh, compatible versions of Mercurial must be installed on both the local and remote sides, and available through your shell's search path on the remote side.
8. Watching files
CVS lets you "put a watch" on files, which requires that other developers run cvs edit before they can edit a file. Mercurial has no corresponding concept, since a Mercurial Repository is a single-user entity that is not "connected" to any other.
9. Binary files
The delta algorithm used by Mercurial handles text and binary files equally well, this meaning that only the differences between revisions are stored. On the other hand, CVS was designed to work with ASCII text, and handles binary files as if they were text (i.e., treating the contents as lines separated by LF characters, and storing line-by-line deltas between revisions). For most binary files, this is very wasteful.
See workflow paragraph for remaining difficulties in using BinaryFiles with mercurial.
10. Keywords expansion
CVS expands keywords such as $Revision: 1.12 $ by adding information from it. This feature is not in Mercurial - see http://www.selenic.com/pipermail/mercurial/2005-August/003887.html, KeywordPlan, KeywordExtension.