comparison text/learning_mercurial_in_workflows.txt @ 107:ee4b04bac02c

workflows: moved the workflow tutorial into learning_mercurial_in_workflows.txt and added a note pointing to that in workflows.txt
author Arne Babenhauserheide <bab@draketo.de>
date Wed, 22 Apr 2009 13:35:03 +0200
parents text/workflows.txt@cdcc94ca41e7
children ed683ad3947f
comparison
equal deleted inserted replaced
106:cdcc94ca41e7 107:ee4b04bac02c
1 = Learning Mercurial in Workflows =
2
3 With Mercurial you can use a multitude of different workflows. This page shows some of them, including their use cases.
4
5 It is intended to make it easier for you to create your own workflow.
6
7 To write this page we gathered [real life workflows](wiki - workflows), so every more complex workflow in here has proven itself in real life usage. We begin with basic workflows and then go on to more complex examples.
8
9 <!--Structure:
10 * For whom? -> Why?
11 * What do you need? -> Resources + extensions
12 * Single Developer workflow
13 * Sharing changes. -->
14
15 <!-- Plan
16
17 * Simple workflows without extensions
18
19 * Complex Workflows, including collaborative patch development and similar.
20
21 * Smoothing workflows with extensions -> i.e. shelve before merging.
22
23 -->
24
25 == Sysadmin workflow ==
26
27 === Use Case ===
28
29 The first workflow is also the easiest one: You're a sysadmin and you want to use Mercurial to be able to look back when you did which changes.
30
31 This workflow only requires an installed Mercurial and write access to some file storage (you almost definitely have that :) ). It shows the basic technics for more complex workflows.
32
33 === Workflow ===
34
35 ==== Initialize the project ====
36
37 <code>$ hg init project</code>
38
39 ==== Add files and track them ====
40
41 <code>$ cd project
42 $ (add files)
43 $ hg add </code>
44
45 Note: You can also go into an existing directory with files and init the repository there.
46
47 $ cd project
48 $ hg init
49
50 You can also just add specific files instead of all files in the directory. Mercurial will then track only these files and won't know about the others. The following tells mercurial to track all files beginning with "file0" as well as file10, file11 and file12.
51
52 $ hg add file0* file10 file11 file12
53
54 ==== Save changes ====
55
56 $ (do some changes)
57
58 see which files changed, which have been added or removed, and which aren't tracked yet.
59
60 $ hg status
61
62 see the exact changes.
63
64 $ hg diff
65
66 commit the changes.
67
68 $ hg commit
69
70 now an editor pops up and asks you for a commit message. Upon saving and closing the editor, your changes have been stored by Mercurial.
71
72 ==== Check your history ====
73
74 $ hg log
75
76 This prints a list of changesets along with their data, the user who committed them (you) and their commit message.
77
78 == Lone developer with linear history ==
79
80 === Use case ===
81
82 The second workflow is still very easy: You're a lone developer and you want to use Mercurial to keep track of your own changes.
83
84 It works just like the sysadmin workflow, with the difference that you go back to earlied changes at times.
85
86 To start a new project, you initialize a repository, add your files and commit whenever you finished a part of your work (atomic commits).
87
88 Also you check your history from time to time, so see how you progressed.
89
90 === Workflow ===
91
92 ==== Basics from sysadmin ====
93
94 Init your project, add files, see changes and commit them.
95
96 <code>$ hg init project
97 $ cd project
98 $ (add files)
99 $ hg add # tell Mercurial to track all files
100 $ (do some changes)
101 $ hg diff # see changes
102 $ hg commit # save changes
103 $ hg log # see history
104
105 ==== Seeing an earlier revision ====
106
107 Different from the sysadmin workflow, you'll want to go back in history at times and undo some changes, for example because it introduced a bug.
108
109 To look at a previous version of your code, you can use update. Let's assume that you want to see revision 3.
110
111 $ hg update 3
112
113 Now your code is back at revision 3, the fourth commit (Mercurial starts couting at 0).
114
115 To update to the most recent revision, you can use "tip" as revision name.
116
117 $ hg update tip
118
119 Note: If at any place any command complains, your best bet is to read what it tells you and follow that advice.
120
121 Note: Instead of "hg update" you can also use the shorthand "hg up". Similarly you can abbreviate "hg commit" to "hg ci".
122
123 ==== Fixing errors in earlier revisions ====
124
125 When you find a bug in some earlier revision you have two options: eaither you can fix it in the current code, or you can go back in history and fix the code exactly where you did it.
126
127 To do so, you first update to the old revision, fix the bug and commit it. Afterwards you merge this revision and commit the merge. Don't worry, though: Merging in mercurial is fast and painless, as you'll see in an instant.
128
129 Let's assume the bug was introduced in revision 3.
130
131 $ hg update 3
132 $ (fix the bug)
133 $ hg commit
134
135 Now the fix is already stored in history. We just need to merge it with the current version of your code.
136
137 $ hg merge
138
139 If there are conflicts use "hg resolve" - that's also what merge tells you to do in case of conflicts.
140
141 $ hg commit
142
143 At this point, your fix is merged with all your other work, and you can just go on coding. Additionally the history shows clearly where you fixed the bug, so you'll always be able to check where the bug was.
144
145
146 So now you can initialize repositories, save changes,
147
148 == Seperate features ==
149
150 === Use Case ===
151
152 At times you'll be working on several features in parallel. If you want to avoid mixing incomplete code versions, you can create clones of your local repository and work on each feature in its own code directory.
153
154 After finishing your feature you then "pull" it back into your main directory and "merge" the changes.
155
156 === Workflow ===
157
158 $ hg clone project feature1
159 $ cd feature1
160 $ (do some changes and commits)
161 $ cd ../project
162 $ hg pull ../feature1
163
164 Now you have the history of feature1 inside your project, but they aren't yet visible. Instead they are only stored inside the .hg directory inside the project.
165
166 From now on we'll use the name "repository" for a directory which has a .hg directory with Mercurial history.
167
168 If you didn't do any changes in the project, while you were working on feature1, you can just update, but it is more likely that you'll have done some changes. In that case, it's time for merging.
169
170 Merge feature1 into the project code:
171
172 $ hg merge
173
174 If there are conflicts use "hg resolve" - that's also what merge tells you to do in case of conflicts.
175
176 $ hg commit -m "merged feature1"
177
178 You can create an arbitrary number of clones and also carry them around on USB sticks. Also you can use them to synchronize your work at home and at work.
179
180 == Sharing changes ==
181
182 === Use Case ===
183
184 Now we go one step further: You are no longer alone, and you want to share your changes with others and include their changes.
185
186 The basic requirement for that is that you have to be able to see the changes of others.
187
188 Mercurial allows you to do that very easily by including a simple webserver from which you can pull changes just as you can pull changes from local clones.
189
190 There are a few other ways to share changes, though. Instead of using the builtin webserver, you can also send the changes by email or setup a shared repository, to where you "push" changes instead of pulling them.
191
192 === Workflow ===
193
194 ==== Using the builtin webserver ====
195
196 This is the easiest way to quickly share changes.
197
198 First the one who wants to share his changes creates the webserver
199
200 $ hg serve
201
202 Now all others can point their browsers to his IP address (i.e. 192.168.178.100) at port 8000. They will then see all his history there and can sdecide if they want to pull his changes.
203
204 $ firefox http://192.168.178.100:8000
205
206 If they decide to include the changes, they just pull from the same URL
207
208 $ hg pull http://192.168.178.100:8000
209
210 At this point you all can work as if you had pulled from a local repository. All the data is now in your individual repositories and you can merge the changes and work with them without needing any connection to the served repository.
211
212 ==== Sending changes by email ====
213
214 ==== Using a shared repository ====
215
216 -> bitbucket