From df17f6d5070ce81afdb7a46fd955b7c9b43cf50a Mon Sep 17 00:00:00 2001 From: Anton Khirnov Date: Sun, 16 Jan 2011 17:16:48 +0000 Subject: [PATCH] Add git-howto. mostly written by Luca. Originally committed as revision 26389 to svn://svn.ffmpeg.org/ffmpeg/trunk --- doc/git-howto.txt | 227 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 227 insertions(+) create mode 100644 doc/git-howto.txt diff --git a/doc/git-howto.txt b/doc/git-howto.txt new file mode 100644 index 0000000000..11f96803cd --- /dev/null +++ b/doc/git-howto.txt @@ -0,0 +1,227 @@ + +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 --help + man git- + +shows information about the subcommand . + +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: + + You can get git from http://git-scm.com/ + + +1. Cloning the source tree: + + git clone git://git.videolan.org/ffmpeg + + This will put the FFmpeg sources into the directory . + + git clone git@git.videolan.org:ffmpeg + + This will put the FFmpeg sources into the directory and let + you push back your changes to the remote repository. + + +2. Updating the source tree to the latest revision: + + git pull + + pulls in the latest changes from the repository to your local master 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 useful to keep all your local changes at the top of your + tree. + + +3. Adding/removing files/directories: + + git add [-A] + git rm [-r] + + 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 + + will show all local modifications in your working directory as unified diff. + + +5. Inspecting the changelog: + + git log + + You may also use the graphical tools like gitview or gitk or the web + interface available at http://git.videolan.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 doublecheck 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 -wb + + Also check the output of + + git status + + to make sure you don't have untracked files or deletions. + + git add [-i|-p|-A] + + 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 throught + + 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 + + git revert will generate a revert commit. This will not make the faulty + commit disappear from the history. + + git reset + + git reset will uncommit the changes till 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 [-o directory] + + will generate a set of patches out of the current branch starting from + commit. By default the patches are created in the current directory. + +11. Sending patches for review + + git send-email + + 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. + +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 + + 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 + + Will push the changes to the remote repository. Omitting refspec makes git + push update all the remote branches matching the local ones. + +Contact the project admins if you have technical +problems with the GIT server.