Commit | Line | Data |
---|---|---|
2ba45a60 DM |
1 | \input texinfo @c -*- texinfo -*- |
2 | ||
3 | @settitle Using git to develop FFmpeg | |
4 | ||
5 | @titlepage | |
6 | @center @titlefont{Using git to develop FFmpeg} | |
7 | @end titlepage | |
8 | ||
9 | @top | |
10 | ||
11 | @contents | |
12 | ||
13 | @chapter Introduction | |
14 | ||
15 | This document aims in giving some quick references on a set of useful git | |
16 | commands. You should always use the extensive and detailed documentation | |
17 | provided directly by git: | |
18 | ||
19 | @example | |
20 | git --help | |
21 | man git | |
22 | @end example | |
23 | ||
24 | shows you the available subcommands, | |
25 | ||
26 | @example | |
27 | git <command> --help | |
28 | man git-<command> | |
29 | @end example | |
30 | ||
31 | shows information about the subcommand <command>. | |
32 | ||
33 | Additional information could be found on the | |
34 | @url{http://gitref.org, Git Reference} website | |
35 | ||
36 | For more information about the Git project, visit the | |
37 | ||
38 | @url{http://git-scm.com/, Git website} | |
39 | ||
40 | Consult these resources whenever you have problems, they are quite exhaustive. | |
41 | ||
42 | What follows now is a basic introduction to Git and some FFmpeg-specific | |
43 | guidelines to ease the contribution to the project | |
44 | ||
45 | @chapter Basics Usage | |
46 | ||
47 | @section Get GIT | |
48 | ||
49 | You can get git from @url{http://git-scm.com/} | |
50 | Most distribution and operating system provide a package for it. | |
51 | ||
52 | ||
53 | @section Cloning the source tree | |
54 | ||
55 | @example | |
56 | git clone git://source.ffmpeg.org/ffmpeg <target> | |
57 | @end example | |
58 | ||
59 | This will put the FFmpeg sources into the directory @var{<target>}. | |
60 | ||
61 | @example | |
62 | git clone git@@source.ffmpeg.org:ffmpeg <target> | |
63 | @end example | |
64 | ||
65 | This will put the FFmpeg sources into the directory @var{<target>} and let | |
66 | you push back your changes to the remote repository. | |
67 | ||
68 | Make sure that you do not have Windows line endings in your checkouts, | |
69 | otherwise you may experience spurious compilation failures. One way to | |
70 | achieve this is to run | |
71 | ||
72 | @example | |
73 | git config --global core.autocrlf false | |
74 | @end example | |
75 | ||
76 | ||
77 | @section Updating the source tree to the latest revision | |
78 | ||
79 | @example | |
80 | git pull (--rebase) | |
81 | @end example | |
82 | ||
83 | pulls in the latest changes from the tracked branch. The tracked branch | |
84 | can be remote. By default the master branch tracks the branch master in | |
85 | the remote origin. | |
86 | ||
87 | @float IMPORTANT | |
88 | @command{--rebase} (see below) is recommended. | |
89 | @end float | |
90 | ||
91 | @section Rebasing your local branches | |
92 | ||
93 | @example | |
94 | git pull --rebase | |
95 | @end example | |
96 | ||
97 | fetches the changes from the main repository and replays your local commits | |
98 | over it. This is required to keep all your local changes at the top of | |
99 | FFmpeg's master tree. The master tree will reject pushes with merge commits. | |
100 | ||
101 | ||
102 | @section Adding/removing files/directories | |
103 | ||
104 | @example | |
105 | git add [-A] <filename/dirname> | |
106 | git rm [-r] <filename/dirname> | |
107 | @end example | |
108 | ||
109 | GIT needs to get notified of all changes you make to your working | |
110 | directory that makes files appear or disappear. | |
111 | Line moves across files are automatically tracked. | |
112 | ||
113 | ||
114 | @section Showing modifications | |
115 | ||
116 | @example | |
117 | git diff <filename(s)> | |
118 | @end example | |
119 | ||
120 | will show all local modifications in your working directory as unified diff. | |
121 | ||
122 | ||
123 | @section Inspecting the changelog | |
124 | ||
125 | @example | |
126 | git log <filename(s)> | |
127 | @end example | |
128 | ||
129 | You may also use the graphical tools like gitview or gitk or the web | |
130 | interface available at http://source.ffmpeg.org/ | |
131 | ||
132 | @section Checking source tree status | |
133 | ||
134 | @example | |
135 | git status | |
136 | @end example | |
137 | ||
138 | detects all the changes you made and lists what actions will be taken in case | |
139 | of a commit (additions, modifications, deletions, etc.). | |
140 | ||
141 | ||
142 | @section Committing | |
143 | ||
144 | @example | |
145 | git diff --check | |
146 | @end example | |
147 | ||
148 | to double check your changes before committing them to avoid trouble later | |
149 | on. All experienced developers do this on each and every commit, no matter | |
150 | how small. | |
151 | Every one of them has been saved from looking like a fool by this many times. | |
152 | It's very easy for stray debug output or cosmetic modifications to slip in, | |
153 | please avoid problems through this extra level of scrutiny. | |
154 | ||
155 | For cosmetics-only commits you should get (almost) empty output from | |
156 | ||
157 | @example | |
158 | git diff -w -b <filename(s)> | |
159 | @end example | |
160 | ||
161 | Also check the output of | |
162 | ||
163 | @example | |
164 | git status | |
165 | @end example | |
166 | ||
167 | to make sure you don't have untracked files or deletions. | |
168 | ||
169 | @example | |
170 | git add [-i|-p|-A] <filenames/dirnames> | |
171 | @end example | |
172 | ||
173 | Make sure you have told git your name and email address | |
174 | ||
175 | @example | |
176 | git config --global user.name "My Name" | |
177 | git config --global user.email my@@email.invalid | |
178 | @end example | |
179 | ||
180 | Use @var{--global} to set the global configuration for all your git checkouts. | |
181 | ||
182 | Git will select the changes to the files for commit. Optionally you can use | |
183 | the interactive or the patch mode to select hunk by hunk what should be | |
184 | added to the commit. | |
185 | ||
186 | ||
187 | @example | |
188 | git commit | |
189 | @end example | |
190 | ||
191 | Git will commit the selected changes to your current local branch. | |
192 | ||
193 | You will be prompted for a log message in an editor, which is either | |
194 | set in your personal configuration file through | |
195 | ||
196 | @example | |
197 | git config --global core.editor | |
198 | @end example | |
199 | ||
200 | or set by one of the following environment variables: | |
201 | @var{GIT_EDITOR}, @var{VISUAL} or @var{EDITOR}. | |
202 | ||
203 | Log messages should be concise but descriptive. Explain why you made a change, | |
204 | what you did will be obvious from the changes themselves most of the time. | |
205 | Saying just "bug fix" or "10l" is bad. Remember that people of varying skill | |
206 | levels look at and educate themselves while reading through your code. Don't | |
207 | include filenames in log messages, Git provides that information. | |
208 | ||
209 | Possibly make the commit message have a terse, descriptive first line, an | |
210 | empty line and then a full description. The first line will be used to name | |
211 | the patch by git format-patch. | |
212 | ||
213 | @section Preparing a patchset | |
214 | ||
215 | @example | |
216 | git format-patch <commit> [-o directory] | |
217 | @end example | |
218 | ||
219 | will generate a set of patches for each commit between @var{<commit>} and | |
220 | current @var{HEAD}. E.g. | |
221 | ||
222 | @example | |
223 | git format-patch origin/master | |
224 | @end example | |
225 | ||
226 | will generate patches for all commits on current branch which are not | |
227 | present in upstream. | |
228 | A useful shortcut is also | |
229 | ||
230 | @example | |
231 | git format-patch -n | |
232 | @end example | |
233 | ||
234 | which will generate patches from last @var{n} commits. | |
235 | By default the patches are created in the current directory. | |
236 | ||
237 | @section Sending patches for review | |
238 | ||
239 | @example | |
240 | git send-email <commit list|directory> | |
241 | @end example | |
242 | ||
243 | will send the patches created by @command{git format-patch} or directly | |
244 | generates them. All the email fields can be configured in the global/local | |
245 | configuration or overridden by command line. | |
246 | Note that this tool must often be installed separately (e.g. @var{git-email} | |
247 | package on Debian-based distros). | |
248 | ||
249 | ||
250 | @section Renaming/moving/copying files or contents of files | |
251 | ||
252 | Git automatically tracks such changes, making those normal commits. | |
253 | ||
254 | @example | |
255 | mv/cp path/file otherpath/otherfile | |
256 | git add [-A] . | |
257 | git commit | |
258 | @end example | |
259 | ||
260 | ||
261 | @chapter Git configuration | |
262 | ||
263 | In order to simplify a few workflows, it is advisable to configure both | |
264 | your personal Git installation and your local FFmpeg repository. | |
265 | ||
266 | @section Personal Git installation | |
267 | ||
268 | Add the following to your @file{~/.gitconfig} to help @command{git send-email} | |
269 | and @command{git format-patch} detect renames: | |
270 | ||
271 | @example | |
272 | [diff] | |
273 | renames = copy | |
274 | @end example | |
275 | ||
276 | @section Repository configuration | |
277 | ||
278 | In order to have @command{git send-email} automatically send patches | |
279 | to the ffmpeg-devel mailing list, add the following stanza | |
280 | to @file{/path/to/ffmpeg/repository/.git/config}: | |
281 | ||
282 | @example | |
283 | [sendemail] | |
284 | to = ffmpeg-devel@@ffmpeg.org | |
285 | @end example | |
286 | ||
287 | @chapter FFmpeg specific | |
288 | ||
289 | @section Reverting broken commits | |
290 | ||
291 | @example | |
292 | git reset <commit> | |
293 | @end example | |
294 | ||
295 | @command{git reset} will uncommit the changes till @var{<commit>} rewriting | |
296 | the current branch history. | |
297 | ||
298 | @example | |
299 | git commit --amend | |
300 | @end example | |
301 | ||
302 | allows one to amend the last commit details quickly. | |
303 | ||
304 | @example | |
305 | git rebase -i origin/master | |
306 | @end example | |
307 | ||
308 | will replay local commits over the main repository allowing to edit, merge | |
309 | or remove some of them in the process. | |
310 | ||
311 | @float NOTE | |
312 | @command{git reset}, @command{git commit --amend} and @command{git rebase} | |
313 | rewrite history, so you should use them ONLY on your local or topic branches. | |
314 | The main repository will reject those changes. | |
315 | @end float | |
316 | ||
317 | @example | |
318 | git revert <commit> | |
319 | @end example | |
320 | ||
321 | @command{git revert} will generate a revert commit. This will not make the | |
322 | faulty commit disappear from the history. | |
323 | ||
324 | @section Pushing changes to remote trees | |
325 | ||
326 | @example | |
327 | git push | |
328 | @end example | |
329 | ||
330 | Will push the changes to the default remote (@var{origin}). | |
331 | Git will prevent you from pushing changes if the local and remote trees are | |
332 | out of sync. Refer to and to sync the local tree. | |
333 | ||
334 | @example | |
335 | git remote add <name> <url> | |
336 | @end example | |
337 | ||
338 | Will add additional remote with a name reference, it is useful if you want | |
339 | to push your local branch for review on a remote host. | |
340 | ||
341 | @example | |
342 | git push <remote> <refspec> | |
343 | @end example | |
344 | ||
345 | Will push the changes to the @var{<remote>} repository. | |
346 | Omitting @var{<refspec>} makes @command{git push} update all the remote | |
347 | branches matching the local ones. | |
348 | ||
349 | @section Finding a specific svn revision | |
350 | ||
351 | Since version 1.7.1 git supports @var{:/foo} syntax for specifying commits | |
352 | based on a regular expression. see man gitrevisions | |
353 | ||
354 | @example | |
355 | git show :/'as revision 23456' | |
356 | @end example | |
357 | ||
358 | will show the svn changeset @var{r23456}. With older git versions searching in | |
359 | the @command{git log} output is the easiest option (especially if a pager with | |
360 | search capabilities is used). | |
361 | This commit can be checked out with | |
362 | ||
363 | @example | |
364 | git checkout -b svn_23456 :/'as revision 23456' | |
365 | @end example | |
366 | ||
367 | or for git < 1.7.1 with | |
368 | ||
369 | @example | |
370 | git checkout -b svn_23456 $SHA1 | |
371 | @end example | |
372 | ||
373 | where @var{$SHA1} is the commit hash from the @command{git log} output. | |
374 | ||
375 | ||
376 | @chapter pre-push checklist | |
377 | ||
378 | Once you have a set of commits that you feel are ready for pushing, | |
379 | work through the following checklist to doublecheck everything is in | |
380 | proper order. This list tries to be exhaustive. In case you are just | |
381 | pushing a typo in a comment, some of the steps may be unnecessary. | |
382 | Apply your common sense, but if in doubt, err on the side of caution. | |
383 | ||
384 | First, make sure that the commits and branches you are going to push | |
385 | match what you want pushed and that nothing is missing, extraneous or | |
386 | wrong. You can see what will be pushed by running the git push command | |
387 | with --dry-run first. And then inspecting the commits listed with | |
388 | @command{git log -p 1234567..987654}. The @command{git status} command | |
389 | may help in finding local changes that have been forgotten to be added. | |
390 | ||
391 | Next let the code pass through a full run of our testsuite. | |
392 | ||
393 | @itemize | |
394 | @item @command{make distclean} | |
395 | @item @command{/path/to/ffmpeg/configure} | |
396 | @item @command{make check} | |
397 | @item if fate fails due to missing samples run @command{make fate-rsync} and retry | |
398 | @end itemize | |
399 | ||
400 | Make sure all your changes have been checked before pushing them, the | |
401 | testsuite only checks against regressions and that only to some extend. It does | |
402 | obviously not check newly added features/code to be working unless you have | |
403 | added a test for that (which is recommended). | |
404 | ||
405 | Also note that every single commit should pass the test suite, not just | |
406 | the result of a series of patches. | |
407 | ||
408 | Once everything passed, push the changes to your public ffmpeg clone and post a | |
409 | merge request to ffmpeg-devel. You can also push them directly but this is not | |
410 | recommended. | |
411 | ||
412 | @chapter Server Issues | |
413 | ||
414 | Contact the project admins @email{root@@ffmpeg.org} if you have technical | |
415 | problems with the GIT server. |