Cleanup
[ikiwiki.git] / docs / developer / TypicalGitUsage.mdwn
1 # Mastering the DragonFly git repository 
2
3 [[!toc  levels=3]]
4 ## Clone the repository 
5
6
7 First you go in your work directory and clone the DragonFly repository. While ***crater*** is the official repo, you are urged to use one of our (generally much faster) mirrors instead. 
8
9     > git clone -o chlamydia git://chlamydia.fs.ei.tum.de/dragonfly.git
10
11
12
13
14
15 If you are a developer, you should create a ***remote*** entry for pushing to ***crater***:
16
17     
18
19     > git remote add crater ssh://crater.dragonflybsd.org/repository/git/dragonfly.git
20
21
22
23
24
25 Clone creates remote-tracking branches for all branches in the parent repo and creates a local  **master**  branch from the remote  **master**  branch.
26
27
28
29     
30
31     > git branch -a
32
33     
34 * master
35
36       chlamydia/DragonFly_RELEASE_1_10
37
38       chlamydia/DragonFly_RELEASE_1_12
39
40       chlamydia/DragonFly_RELEASE_1_2
41
42       chlamydia/DragonFly_RELEASE_1_4
43
44       chlamydia/DragonFly_RELEASE_1_6
45
46       chlamydia/DragonFly_RELEASE_1_8
47
48       chlamydia/DragonFly_RELEASE_2_0
49
50       chlamydia/HEAD
51
52       chlamydia/master
53
54       chlamydia/repo/hooks
55
56       chlamydia/vendor/ATHEROS
57
58       [...]
59
60       chlamydia/vendor/ZLIB
61
62
63
64
65
66 ## Prepare patches 
67
68
69
70 If you (as a non-developer) made some changes to the DragonFly source and want to get them included in the main repository, send your patches to submit@lists.dragonflybsd.org. git assists you in creating patches which are easy to handle for the developers.
71
72
73
74 ### Example 
75
76  **Note:**  The change in this example is completely useless, it only serves demonstration purposes!
77
78
79
80 At first edit the files you want to change:
81
82     
83
84     > vim README
85
86
87
88 Then review your changes with `git diff`:
89
90     
91
92     > git diff
93
94     diff --git a/README b/README
95
96     index 495a262..6a95d1f 100644
97
98     --- a/README
99
100     +++ b/README
101
102     @@ -59,7 +59,7 @@ lib           System libraries.
103
104      
105
106      libexec                System daemons.
107
108      
109
110     -nrelease       Framework for building the ***live*** CD image.
111
112     +nrelease       Framework for building the ***live CD*** image.
113
114      
115
116      sbin           System commands.
117
118      
119
120
121
122 If you are satisfied with your changes, commit them.   **Note:**  The first line of your commit message should describe your change in a small sentence.  Add more details after one newline.
123
124     
125
126     > git commit -a
127
128     ".git/COMMIT_EDITMSG" 10L, 342C written                                                                              
129
130     Created commit cbb871b: Change parentheses
131
132      1 files changed, 1 insertions(+), 1 deletions(-)
133
134
135
136 Now you can use `git format-patch` to generate a patch file.  This file is ready for submission to submit@. `git format-patch` will generate one file for every commit you did.
137
138     
139
140     > git format-patch origin
141
142     0001-Change-parentheses.patch
143
144     > cat 0001-Change-parentheses.patch
145
146     From cbb871b4588c695f000bc701b4f3c16a0a518991 Mon Sep 17 00:00:00 2001
147
148     From: Matthias Schmidt <matthiasdragonflybsd.org>
149
150     Date: Tue, 2 Dec 2008 09:54:47 +0100
151
152     Subject: [PATCH] Change parentheses
153
154     
155
156     ---
157
158      README |    2 +-
159
160      1 files changed, 1 insertions(+), 1 deletions(-)
161
162     
163
164     diff --git a/README b/README
165
166     index 495a262..6a95d1f 100644
167
168     --- a/README
169
170     +++ b/README
171
172     @@ -59,7 +59,7 @@ lib           System libraries.
173
174      
175
176      libexec                System daemons.
177
178      
179
180     -nrelease       Framework for building the ***live*** CD image.
181
182     +nrelease       Framework for building the ***live CD*** image.
183
184      
185
186      sbin           System commands.
187
188      
189
190     -- 
191
192     1.6.0.2
193
194     
195
196
197
198
199
200 Attach the generated files to a mail and submit it.  Write some lines about your intention and why you changed what ...
201
202
203
204 ## Working with branches 
205
206 It is  **not**  recommended to work directly in your  **master**  branch, except maybe for one-liners. Branches in git are very cheap, so just keep your  **master**  branch pure, and always work on a different local branch.
207
208
209
210 Say you want to work on a simple change. Just create a temporary branch, make the change and commit it.
211
212
213
214
215     
216
217     > git checkout -b work      # you're now in the work branch
218
219     > vim what/ever.c
220
221     > git commit -a
222
223
224
225
226
227 Now, you can switch back to  **master** , merge in the changes in your  **work**  branch and push away:
228
229
230
231     
232
233     > git checkout master      # you're now in the master branch
234
235     > git merge work           # now master has your changes
236
237
238
239
240
241 Afterwards, you may (or not, if you want to do further development) want to delete the  **work**  branch by
242
243
244
245     
246
247     > git branch -d work
248
249
250
251
252
253 For more complex changes, you probably want to create a longer-lived branch. For example
254
255
256
257     
258
259     > git checkout -b myfeature
260
261
262
263
264
265 You can work in the  **myfeature**  branch until your feature is ready. You can commit there as often as you like. If your work goes on for a significant amount of time, you will want to merge with the upstream  **master**  from time to time. It is recommended that you use git rebase, so that the merge points won't show up in the repo history on crater (they don't really add much information). For this, you'd do:
266
267
268
269     
270
271     > git checkout master
272
273     > git pull
274
275     > git checkout myfeature
276
277     > git rebase master
278
279
280
281
282
283 ## Push your work upstream 
284
285 When you judge that your code is ready for inclusion in mainline, you can merge it into your local  **master**  branch and push away:
286
287
288
289     
290
291     > git checkout master
292
293     > git merge myfeature
294
295     > git push crater
296
297
298
299
300
301 as the command will not push any branch that is not in the remote repository.
302