git.sesse.net Git - ffmpeg/blob - doc/git-howto.texi

   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
  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 Libav-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://git.libav.org/libav.git <target>
  57 @end example
  58
  59 This will put the Libav sources into the directory @var{<target>}.
  60
  61 @example
  62 git clone git@@git.libav.org:libav.git <target>
  63 @end example
  64
  65 This will put the Libav 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 Since merge commits are forbidden @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 Libav'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://git.libav.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 Libav 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{git@@libav.org} if you have technical
 344 problems with the GIT server.