Merge remote-tracking branch 'qatar/master'
[ffmpeg.git] / doc / git-howto.texi
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
69 @section Updating the source tree to the latest revision
70
71 @example
72 git pull (--rebase)
73 @end example
74
75 pulls in the latest changes from the tracked branch. The tracked branch
76 can be remote. By default the master branch tracks the branch master in
77 the remote origin.
78
79 @float IMPORTANT
80 @command{--rebase} (see below) is recommended.
81 @end float
82
83 @section Rebasing your local branches
84
85 @example
86 git pull --rebase
87 @end example
88
89 fetches the changes from the main repository and replays your local commits
90 over it. This is required to keep all your local changes at the top of
91 FFmpeg's master tree. The master tree will reject pushes with merge commits.
92
93
94 @section Adding/removing files/directories
95
96 @example
97 git add [-A] <filename/dirname>
98 git rm [-r] <filename/dirname>
99 @end example
100
101 GIT needs to get notified of all changes you make to your working
102 directory that makes files appear or disappear.
103 Line moves across files are automatically tracked.
104
105
106 @section Showing modifications
107
108 @example
109 git diff <filename(s)>
110 @end example
111
112 will show all local modifications in your working directory as unified diff.
113
114
115 @section Inspecting the changelog
116
117 @example
118 git log <filename(s)>
119 @end example
120
121 You may also use the graphical tools like gitview or gitk or the web
122 interface available at http://source.ffmpeg.org/
123
124 @section Checking source tree status
125
126 @example
127 git status
128 @end example
129
130 detects all the changes you made and lists what actions will be taken in case
131 of a commit (additions, modifications, deletions, etc.).
132
133
134 @section Committing
135
136 @example
137 git diff --check
138 @end example
139
140 to double check your changes before committing them to avoid trouble later
141 on. All experienced developers do this on each and every commit, no matter
142 how small.
143 Every one of them has been saved from looking like a fool by this many times.
144 It's very easy for stray debug output or cosmetic modifications to slip in,
145 please avoid problems through this extra level of scrutiny.
146
147 For cosmetics-only commits you should get (almost) empty output from
148
149 @example
150 git diff -w -b <filename(s)>
151 @end example
152
153 Also check the output of
154
155 @example
156 git status
157 @end example
158
159 to make sure you don't have untracked files or deletions.
160
161 @example
162 git add [-i|-p|-A] <filenames/dirnames>
163 @end example
164
165 Make sure you have told git your name and email address
166
167 @example
168 git config --global user.name "My Name"
169 git config --global user.email my@@email.invalid
170 @end example
171
172 Use @var{--global} to set the global configuration for all your git checkouts.
173
174 Git will select the changes to the files for commit. Optionally you can use
175 the interactive or the patch mode to select hunk by hunk what should be
176 added to the commit.
177
178
179 @example
180 git commit
181 @end example
182
183 Git will commit the selected changes to your current local branch.
184
185 You will be prompted for a log message in an editor, which is either
186 set in your personal configuration file through
187
188 @example
189 git config --global core.editor
190 @end example
191
192 or set by one of the following environment variables:
193 @var{GIT_EDITOR}, @var{VISUAL} or @var{EDITOR}.
194
195 Log messages should be concise but descriptive. Explain why you made a change,
196 what you did will be obvious from the changes themselves most of the time.
197 Saying just "bug fix" or "10l" is bad. Remember that people of varying skill
198 levels look at and educate themselves while reading through your code. Don't
199 include filenames in log messages, Git provides that information.
200
201 Possibly make the commit message have a terse, descriptive first line, an
202 empty line and then a full description. The first line will be used to name
203 the patch by git format-patch.
204
205 @section Preparing a patchset
206
207 @example
208 git format-patch <commit> [-o directory]
209 @end example
210
211 will generate a set of patches for each commit between @var{<commit>} and
212 current @var{HEAD}. E.g.
213
214 @example
215 git format-patch origin/master
216 @end example
217
218 will generate patches for all commits on current branch which are not
219 present in upstream.
220 A useful shortcut is also
221
222 @example
223 git format-patch -n
224 @end example
225
226 which will generate patches from last @var{n} commits.
227 By default the patches are created in the current directory.
228
229 @section Sending patches for review
230
231 @example
232 git send-email <commit list|directory>
233 @end example
234
235 will send the patches created by @command{git format-patch} or directly
236 generates them. All the email fields can be configured in the global/local
237 configuration or overridden by command line.
238 Note that this tool must often be installed separately (e.g. @var{git-email}
239 package on Debian-based distros).
240
241
242 @section Renaming/moving/copying files or contents of files
243
244 Git automatically tracks such changes, making those normal commits.
245
246 @example
247 mv/cp path/file otherpath/otherfile
248 git add [-A] .
249 git commit
250 @end example
251
252
253 @chapter FFmpeg specific
254
255 @section Reverting broken commits
256
257 @example
258 git reset <commit>
259 @end example
260
261 @command{git reset} will uncommit the changes till @var{<commit>} rewriting
262 the current branch history.
263
264 @example
265 git commit --amend
266 @end example
267
268 allows to amend the last commit details quickly.
269
270 @example
271 git rebase -i origin/master
272 @end example
273
274 will replay local commits over the main repository allowing to edit, merge
275 or remove some of them in the process.
276
277 @float NOTE
278 @command{git reset}, @command{git commit --amend} and @command{git rebase}
279 rewrite history, so you should use them ONLY on your local or topic branches.
280 The main repository will reject those changes.
281 @end float
282
283 @example
284 git revert <commit>
285 @end example
286
287 @command{git revert} will generate a revert commit. This will not make the
288 faulty commit disappear from the history.
289
290 @section Pushing changes to remote trees
291
292 @example
293 git push
294 @end example
295
296 Will push the changes to the default remote (@var{origin}).
297 Git will prevent you from pushing changes if the local and remote trees are
298 out of sync. Refer to and to sync the local tree.
299
300 @example
301 git remote add <name> <url>
302 @end example
303
304 Will add additional remote with a name reference, it is useful if you want
305 to push your local branch for review on a remote host.
306
307 @example
308 git push <remote> <refspec>
309 @end example
310
311 Will push the changes to the @var{<remote>} repository.
312 Omitting @var{<refspec>} makes @command{git push} update all the remote
313 branches matching the local ones.
314
315 @section Finding a specific svn revision
316
317 Since version 1.7.1 git supports @var{:/foo} syntax for specifying commits
318 based on a regular expression. see man gitrevisions
319
320 @example
321 git show :/'as revision 23456'
322 @end example
323
324 will show the svn changeset @var{r23456}. With older git versions searching in
325 the @command{git log} output is the easiest option (especially if a pager with
326 search capabilities is used).
327 This commit can be checked out with
328
329 @example
330 git checkout -b svn_23456 :/'as revision 23456'
331 @end example
332
333 or for git < 1.7.1 with
334
335 @example
336 git checkout -b svn_23456 $SHA1
337 @end example
338
339 where @var{$SHA1} is the commit hash from the @command{git log} output.
340
341 @chapter Server Issues
342
343 Contact the project admins @email{root@@ffmpeg.org} if you have technical
344 problems with the GIT server.