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