path: root/doc/git-howto.texi (plain)
blob: 2b4fb8023320ae7f152a1e4a5764640da04a6aa0

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.
436