yading@10: yading@10: About Git write access: yading@10: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ yading@10: yading@10: Before everything else, you should know how to use GIT properly. yading@10: Luckily Git comes with excellent documentation. yading@10: yading@10: git --help yading@10: man git yading@10: yading@10: shows you the available subcommands, yading@10: yading@10: git --help yading@10: man git- yading@10: yading@10: shows information about the subcommand . yading@10: yading@10: The most comprehensive manual is the website Git Reference yading@10: yading@10: http://gitref.org/ yading@10: yading@10: For more information about the Git project, visit yading@10: yading@10: http://git-scm.com/ yading@10: yading@10: Consult these resources whenever you have problems, they are quite exhaustive. yading@10: yading@10: You do not need a special username or password. yading@10: All you need is to provide a ssh public key to the Git server admin. yading@10: yading@10: What follows now is a basic introduction to Git and some FFmpeg-specific yading@10: guidelines. Read it at least once, if you are granted commit privileges to the yading@10: FFmpeg project you are expected to be familiar with these rules. yading@10: yading@10: yading@10: yading@10: I. BASICS: yading@10: ========== yading@10: yading@10: 0. Get GIT: yading@10: yading@10: Most distributions have a git package, if not yading@10: You can get git from http://git-scm.com/ yading@10: yading@10: yading@10: 1. Cloning the source tree: yading@10: yading@10: git clone git://source.ffmpeg.org/ffmpeg yading@10: yading@10: This will put the FFmpeg sources into the directory . yading@10: yading@10: git clone git@source.ffmpeg.org:ffmpeg yading@10: yading@10: This will put the FFmpeg sources into the directory and let yading@10: you push back your changes to the remote repository. yading@10: yading@10: yading@10: 2. Updating the source tree to the latest revision: yading@10: yading@10: git pull (--ff-only) yading@10: yading@10: pulls in the latest changes from the tracked branch. The tracked branch yading@10: can be remote. By default the master branch tracks the branch master in yading@10: the remote origin. yading@10: Caveat: Since merge commits are forbidden at least for the initial yading@10: months of git --ff-only or --rebase (see below) are recommended. yading@10: --ff-only will fail and not create merge commits if your branch yading@10: has diverged (has a different history) from the tracked branch. yading@10: yading@10: 2.a Rebasing your local branches: yading@10: yading@10: git pull --rebase yading@10: yading@10: fetches the changes from the main repository and replays your local commits yading@10: over it. This is required to keep all your local changes at the top of yading@10: FFmpeg's master tree. The master tree will reject pushes with merge commits. yading@10: yading@10: yading@10: 3. Adding/removing files/directories: yading@10: yading@10: git add [-A] yading@10: git rm [-r] yading@10: yading@10: GIT needs to get notified of all changes you make to your working yading@10: directory that makes files appear or disappear. yading@10: Line moves across files are automatically tracked. yading@10: yading@10: yading@10: 4. Showing modifications: yading@10: yading@10: git diff yading@10: yading@10: will show all local modifications in your working directory as unified diff. yading@10: yading@10: yading@10: 5. Inspecting the changelog: yading@10: yading@10: git log yading@10: yading@10: You may also use the graphical tools like gitview or gitk or the web yading@10: interface available at http://source.ffmpeg.org yading@10: yading@10: 6. Checking source tree status: yading@10: yading@10: git status yading@10: yading@10: detects all the changes you made and lists what actions will be taken in case yading@10: of a commit (additions, modifications, deletions, etc.). yading@10: yading@10: yading@10: 7. Committing: yading@10: yading@10: git diff --check yading@10: yading@10: to double check your changes before committing them to avoid trouble later yading@10: on. All experienced developers do this on each and every commit, no matter yading@10: how small. yading@10: Every one of them has been saved from looking like a fool by this many times. yading@10: It's very easy for stray debug output or cosmetic modifications to slip in, yading@10: please avoid problems through this extra level of scrutiny. yading@10: yading@10: For cosmetics-only commits you should get (almost) empty output from yading@10: yading@10: git diff -w -b yading@10: yading@10: Also check the output of yading@10: yading@10: git status yading@10: yading@10: to make sure you don't have untracked files or deletions. yading@10: yading@10: git add [-i|-p|-A] yading@10: yading@10: Make sure you have told git your name and email address, e.g. by running yading@10: git config --global user.name "My Name" yading@10: git config --global user.email my@email.invalid yading@10: (--global to set the global configuration for all your git checkouts). yading@10: yading@10: Git will select the changes to the files for commit. Optionally you can use yading@10: the interactive or the patch mode to select hunk by hunk what should be yading@10: added to the commit. yading@10: yading@10: git commit yading@10: yading@10: Git will commit the selected changes to your current local branch. yading@10: yading@10: You will be prompted for a log message in an editor, which is either yading@10: set in your personal configuration file through yading@10: yading@10: git config core.editor yading@10: yading@10: or set by one of the following environment variables: yading@10: GIT_EDITOR, VISUAL or EDITOR. yading@10: yading@10: Log messages should be concise but descriptive. Explain why you made a change, yading@10: what you did will be obvious from the changes themselves most of the time. yading@10: Saying just "bug fix" or "10l" is bad. Remember that people of varying skill yading@10: levels look at and educate themselves while reading through your code. Don't yading@10: include filenames in log messages, Git provides that information. yading@10: yading@10: Possibly make the commit message have a terse, descriptive first line, an yading@10: empty line and then a full description. The first line will be used to name yading@10: the patch by git format-patch. yading@10: yading@10: yading@10: 8. Renaming/moving/copying files or contents of files: yading@10: yading@10: Git automatically tracks such changes, making those normal commits. yading@10: yading@10: mv/cp path/file otherpath/otherfile yading@10: yading@10: git add [-A] . yading@10: yading@10: git commit yading@10: yading@10: Do not move, rename or copy files of which you are not the maintainer without yading@10: discussing it on the mailing list first! yading@10: yading@10: 9. Reverting broken commits yading@10: yading@10: git revert yading@10: yading@10: git revert will generate a revert commit. This will not make the faulty yading@10: commit disappear from the history. yading@10: yading@10: git reset yading@10: yading@10: git reset will uncommit the changes till rewriting the current yading@10: branch history. yading@10: yading@10: git commit --amend yading@10: yading@10: allows to amend the last commit details quickly. yading@10: yading@10: git rebase -i origin/master yading@10: yading@10: will replay local commits over the main repository allowing to edit, yading@10: merge or remove some of them in the process. yading@10: yading@10: Note that the reset, commit --amend and rebase rewrite history, so you yading@10: should use them ONLY on your local or topic branches. yading@10: yading@10: The main repository will reject those changes. yading@10: yading@10: 10. Preparing a patchset. yading@10: yading@10: git format-patch [-o directory] yading@10: yading@10: will generate a set of patches for each commit between and yading@10: current HEAD. E.g. yading@10: yading@10: git format-patch origin/master yading@10: yading@10: will generate patches for all commits on current branch which are not yading@10: present in upstream. yading@10: A useful shortcut is also yading@10: yading@10: git format-patch -n yading@10: yading@10: which will generate patches from last n commits. yading@10: By default the patches are created in the current directory. yading@10: yading@10: 11. Sending patches for review yading@10: yading@10: git send-email yading@10: yading@10: will send the patches created by git format-patch or directly generates yading@10: them. All the email fields can be configured in the global/local yading@10: configuration or overridden by command line. yading@10: Note that this tool must often be installed separately (e.g. git-email yading@10: package on Debian-based distros). yading@10: yading@10: 12. Pushing changes to remote trees yading@10: yading@10: git push yading@10: yading@10: Will push the changes to the default remote (origin). yading@10: Git will prevent you from pushing changes if the local and remote trees are yading@10: out of sync. Refer to 2 and 2.a to sync the local tree. yading@10: yading@10: git remote add yading@10: yading@10: Will add additional remote with a name reference, it is useful if you want yading@10: to push your local branch for review on a remote host. yading@10: yading@10: git push yading@10: yading@10: Will push the changes to the remote repository. Omitting refspec makes git yading@10: push update all the remote branches matching the local ones. yading@10: yading@10: 13. Finding a specific svn revision yading@10: yading@10: Since version 1.7.1 git supports ':/foo' syntax for specifying commits yading@10: based on a regular expression. see man gitrevisions yading@10: yading@10: git show :/'as revision 23456' yading@10: yading@10: will show the svn changeset r23456. With older git versions searching in yading@10: the git log output is the easiest option (especially if a pager with yading@10: search capabilities is used). yading@10: This commit can be checked out with yading@10: yading@10: git checkout -b svn_23456 :/'as revision 23456' yading@10: yading@10: or for git < 1.7.1 with yading@10: yading@10: git checkout -b svn_23456 $SHA1 yading@10: yading@10: where $SHA1 is the commit SHA1 from the 'git log' output. yading@10: yading@10: yading@10: Contact the project admins if you have technical yading@10: problems with the GIT server.