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