1 \input texinfo @c -*- texinfo -*-
3 @settitle Using git to develop FFmpeg
6 @center @titlefont{Using git to develop FFmpeg}
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:
24 shows you the available subcommands,
31 shows information about the subcommand <command>.
33 Additional information could be found on the
34 @url{http://gitref.org, Git Reference} website
36 For more information about the Git project, visit the
38 @url{http://git-scm.com/, Git website}
40 Consult these resources whenever you have problems, they are quite exhaustive.
42 What follows now is a basic introduction to Git and some FFmpeg-specific
43 guidelines to ease the contribution to the project
49 You can get git from @url{http://git-scm.com/}
50 Most distribution and operating system provide a package for it.
53 @section Cloning the source tree
56 git clone git://source.ffmpeg.org/ffmpeg <target>
59 This will put the FFmpeg sources into the directory @var{<target>}.
62 git clone git@@source.ffmpeg.org:ffmpeg <target>
65 This will put the FFmpeg sources into the directory @var{<target>} and let
66 you push back your changes to the remote repository.
69 @section Updating the source tree to the latest revision
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
80 @command{--rebase} (see below) is recommended.
83 @section Rebasing your local branches
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.
94 @section Adding/removing files/directories
97 git add [-A] <filename/dirname>
98 git rm [-r] <filename/dirname>
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.
106 @section Showing modifications
109 git diff <filename(s)>
112 will show all local modifications in your working directory as unified diff.
115 @section Inspecting the changelog
118 git log <filename(s)>
121 You may also use the graphical tools like gitview or gitk or the web
122 interface available at http://source.ffmpeg.org/
124 @section Checking source tree status
130 detects all the changes you made and lists what actions will be taken in case
131 of a commit (additions, modifications, deletions, etc.).
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
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.
147 For cosmetics-only commits you should get (almost) empty output from
150 git diff -w -b <filename(s)>
153 Also check the output of
159 to make sure you don't have untracked files or deletions.
162 git add [-i|-p|-A] <filenames/dirnames>
165 Make sure you have told git your name and email address
168 git config --global user.name "My Name"
169 git config --global user.email my@@email.invalid
172 Use @var{--global} to set the global configuration for all your git checkouts.
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
183 Git will commit the selected changes to your current local branch.
185 You will be prompted for a log message in an editor, which is either
186 set in your personal configuration file through
189 git config --global core.editor
192 or set by one of the following environment variables:
193 @var{GIT_EDITOR}, @var{VISUAL} or @var{EDITOR}.
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.
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.
205 @section Preparing a patchset
208 git format-patch <commit> [-o directory]
211 will generate a set of patches for each commit between @var{<commit>} and
212 current @var{HEAD}. E.g.
215 git format-patch origin/master
218 will generate patches for all commits on current branch which are not
220 A useful shortcut is also
226 which will generate patches from last @var{n} commits.
227 By default the patches are created in the current directory.
229 @section Sending patches for review
232 git send-email <commit list|directory>
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).
242 @section Renaming/moving/copying files or contents of files
244 Git automatically tracks such changes, making those normal commits.
247 mv/cp path/file otherpath/otherfile
253 @chapter FFmpeg specific
255 @section Reverting broken commits
261 @command{git reset} will uncommit the changes till @var{<commit>} rewriting
262 the current branch history.
268 allows to amend the last commit details quickly.
271 git rebase -i origin/master
274 will replay local commits over the main repository allowing to edit, merge
275 or remove some of them in the process.
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.
287 @command{git revert} will generate a revert commit. This will not make the
288 faulty commit disappear from the history.
290 @section Pushing changes to remote trees
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.
301 git remote add <name> <url>
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.
308 git push <remote> <refspec>
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.
315 @section Finding a specific svn revision
317 Since version 1.7.1 git supports @var{:/foo} syntax for specifying commits
318 based on a regular expression. see man gitrevisions
321 git show :/'as revision 23456'
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
330 git checkout -b svn_23456 :/'as revision 23456'
333 or for git < 1.7.1 with
336 git checkout -b svn_23456 $SHA1
339 where @var{$SHA1} is the commit hash from the @command{git log} output.
341 @chapter Server Issues
343 Contact the project admins @email{root@@ffmpeg.org} if you have technical
344 problems with the GIT server.