Wiki code for How To Use Mercurial (hg) Repositories

Hide Line numbers
1: = How to Use Mercurial (hg) Repositories
2: 
3: == Introduction
4: 
5: Two kinds of source repositories are hosted at opensolaris.org: centralized and distributed. The centralized source management model uses the [[Subversion>>http://subversion.tigris.org/]] (SVN) source control management program. See the [[Subversion help page>>Community Group tools.svn_help]] for information.
6: 
7: Repositories managed in a distributed fashion use the [[Mercurial>>http://www.selenic.com/mercurial/wiki/index.cgi]] source control management program. This page describes Mercurial. The first sections are for developers. The section at the end for Project Leads is labeled "For Project Leads".
8: 
9: == How to install Mercurial
10: 
11: Mercurial is [[available>>Main.downloads]] via OpenSolaris and Solaris Express (build 88 or later).
12: 
13: === Building from source code
14: 
15: The Mercurial Wiki has details [[on building Mercurial from source>>http://www.selenic.com/mercurial/wiki/index.cgi/UnixInstall]]. Mercurial is primarily written in Python, but some of the extensions are in C.
16: 
17: == How to get commit access to opensolaris.org Mercurial repositories
18: 
19: Developers with commit rights will access repositories through their opensolaris.org accounts. Commit rights are managed by Project Leaders. If you do not have an account, sign up to acquire one. Additionally, you will have to [[provide a Secure Shell (SSH) public key>>Project website.ssh_instructions]].
20: 
21:  For anonymous access to a repository, use the user name ’anon’.
22: 
23: == Proxies
24: 
25: If you are behind a firewall that requires that SSH connections be tunnelled through a SOCKS proxy, then your $HOME/.ssh/config file needs to contain a directive like:
26: 
27: {{{
28: 
29: Host *.opensolaris.org
30:     ProxyCommand /usr/lib/ssh/ssh-socks5-proxy-connect -h [socks proxy address] %h %p
31: 
32: }}}
33: 
34: Sun employees should note that proxying should no longer be used from Sun’s internal network. If you have ssh configured to use a proxy, you will eventually start seeing timeouts or other errors as the proxies are being decommissioned.
35: 
36: == How to get started with Mercurial
37: 
38: General information about Mercurial and how to use it is available at the [[Mercurial website>>http://www.selenic.com/mercurial/]]. There you will find a quickstart guide, a tutorial for new users, a FAQ, ’tips and tricks’ and more.
39: 
40:  Information for engineers transitioning from TeamWare is available on the [[How To Transition from Teamware to Mercurial>>Community Group tools.hg_teamware_transition]] page.
41: 
42:  A few common operations are illustrated below, using the [[ON Nevada>>Project onnv.WebHome]] repository as an example.
43: 
44: === Usage
45: 
46: The Mercurial program is named hg (the chemical symbol for Mercury). Every Mercurial command starts with {{code}}hg{{/code}}, followed by the command name, followed by any relevant options and arguments. Just running {{code}}hg{{/code}} on the command line displays a list of commands.
47: 
48: {{{
49: $ hg
50: Mercurial Distributed SCM
51: 
52: basic commands (use "hg help" for the full list or option "-v" for details):
53: 
54: add        add the specified files on the next commit
55: annotate   show changeset information per file line
56: clone      make a copy of an existing repository
57: commit     commit the specified files or all outstanding changes
58: ...
59: 
60: }}}
61: 
62: The help command can be used to get more information about any command.
63: 
64: {{{
65: $ hg help diff
66: hg diff [-a] [-I] [-X] [-r REV1 [-r REV2]] [FILE]...
67: 
68: diff repository (or selected files)
69: ...
70: 
71: }}}
72: 
73: === Getting an initial copy
74: 
75: Use Mercurial’s {{code}}clone{{/code}} subcommand to get a copy of the project repository.
76: 
77: {{{
78: 
79: $ hg clone ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate my-copy
80: requesting all changes
81: adding changesets
82: adding manifests
83: adding file changes
84: added 3196 changesets with 65633 changes to 42834 files
85: 39543 files updated, 0 files merged, 0 files removed, 0 files unresolved
86: 
87: }}}
88: 
89: === Updating a child repository
90: 
91: Use Mercurial’s {{code}}pull{{/code}} and {{code}}update{{/code}} subcommands to acquire any changes since your last pull or clone operation. If there are no pending changes, you’ll see a result like:
92: 
93: {{{
94: 
95: $ cd my-copy
96: $ hg pull
97: pulling from ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate
98: searching for changes
99: no changes found
100: 
101: }}}
102: 
103:  Otherwise, you’ll get output informing you of the number of changesets involved:
104: 
105: {{{
106: 
107: $ hg pull
108: pulling from ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate
109: searching for changes
110: adding changesets
111: adding manifests
112: adding file changes
113: added 503 changesets with 5608 changes to 4444 files
114: (run ’hg update’ to get a working copy)
115: $ hg update
116: 4433 files updated, 0 files merged, 376 files removed, 0 files unresolved
117: 
118: }}}
119: 
120: === Using hg bundles of the ON repository
121: 
122: OpenSolaris mercurial repositories are sometimes provided as "bundles" with a .hg extension. There are two types of bundles - Changesets and Incremental. Changeset bundles are complete standalone bundles. To get a working copy of this bundle, download it from the opensolaris.org downloads page and do the following steps.
123: 
124: {{{
125:  cd /export/work
126:  hg init
127:  hg unbundle {path}/on-hg-bundle-YYYYMMDD.hg
128:  hg update
129: 
130: }}}
131: 
132: Incremental bundles are typically named as "{{code}}on-hg-bundle_yyyymmdd-YYYYMMDD.hg{{/code}}" and contain only incremental changes. They can only be applied to a working copy which contains all changesets up to yyyymmdd and no more. This is verified before the unbundling process by checking the parent property (hg parent) of the bundle. You can apply an incremental bundle to a working copy using the following commands
133: 
134: {{{
135:  cd /export/work
136:  hg unbundle on-hg-bundle_yyyymmdd-YYYYMMDD.hg
137:  hg update
138: 
139: }}}
140: 
141: Once you have a working copy, you can clone it and do other operations described below.
142: 
143: === Editing files
144: 
145: There is no equivalent of the sccs edit or wx edit. Mercurial automatically keeps track of modified files.
146: 
147: === Adding files
148: 
149: The equivalent of the wx create command to add files to the workspace is the add command.
150: 
151: {{{
152: hg add file1.c ...
153: }}}
154: 
155: These files will be added to the repository on the next commit.
156: 
157: === Examining differences
158: 
159: The equivalent of the sccs diffs and the wx diffs commands is the diff command.
160: 
161: {{{
162: hg diff
163: }}}
164: 
165: Without any arguments, hg diff will print out the differences between all modified files in the repository. Differences between files are shown using the unified diff format.
166: 
167: === Commiting the changes
168: 
169: The equivalent of the sccs delget and wx delget commands is the commit command.
170: 
171: {{{
172: hg commit
173: }}}
174: 
175: This command drops us into an editor (configured using the {{code}}EDITOR{{/code}} and {{code}}HGEDITOR{{/code}} environment variables) where we can add the putback comments. Once we save the changes and quit the editor, the changes are committed to the repository.
176: 
177: === Putting back the changes to the parent repository
178: 
179: All changes up to this point have been in the working clone repository. The changes can be put back to the parent repository using the push command.
180: 
181: {{{
182: 
183: hg push /ws/onnv-gate
184: 
185: }}}
186: 
187: This is the equivalent of the Teamware command "{{code}}putback -p /ws/onnv-gate{{/code}}". It is not mandatory to provide the path to the repository to push the changes to. If no repository is specified, the changes will be pushed to the repository we cloned from.
188: 
189: The equivalent of the "{{code}}putback -n{{/code}}" command is Mercurial’s "{{code}}outgoing{{/code}}" command.
190: 
191: {{{
192: 
193: hg outgoing
194: hg outgoing ssh://anon@hg.opensolaris.org/hg/onnv/onnv-gate
195: 
196: }}}
197: 
198: == More Information
199: 
200: * [[SCM FAQ>>http://wiki.genunix.org/wiki/index.php/SCM_FAQ]]
201: * [[Mercurial: The Definitive Guide>>http://www.selenic.com/mercurial/wiki/index.cgi/MercurialBook]]
202: * [[tools-discuss>>http://www.opensolaris.org/jive/forum.jspa?forumID=9]]
203: 
204: == For Project Leads: How to set up a Mercurial repository
205: 
206: The creation of a Mercurial repository on opensolaris.org is done through the webpages. You have to be a project leader to create a new repository.
207: 
208: On the main page for a project, there is an item called "SCM Console". This item will lead you to the SCM configuration page. Choose "Create Repository". You will be asked to provide a name for the repository, a notification email address, the repository type (Subversion or Mercurial), and whether anonymous access is allowed. Click the "Create" button to add the repository. After the repository has been created successfully, a short summary of the repository name and properties will be shown. You can click the name of the repository in this summary to add/remove committers.
209: 
210: The URL for the repository will be of the format
211: 
212: {{{
213: 
214: ssh://user@hg.opensolaris.org/hg/projectname/reponame
215: 
216: }}}
217: 
218:  Where "projectname" is the name of your project and "reponame" the name of the newly created repository. "user" can be "anon" or the opensolaris.org username of someone who has commit rights to the repository.
219: 
220: There is currently no support for deleting repositories via the website. If you own a repository that you want to go away, please send mail to tonic-ops@sun.com.
OpenSolaris

Top Menu

Wiki code for How To Use Mercurial (hg) Repositories

Search

Collectives

Community Group

Project

User Group

Subsites

Community Group tools Pages
