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