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