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