Add git-howto.

mostly written by Luca.

Originally committed as revision 26389 to svn://svn.ffmpeg.org/ffmpeg/trunk

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 <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:
+
+  You can get git from http://git-scm.com/
+
+
+1. Cloning the source tree:
+
+    git clone git://git.videolan.org/ffmpeg <target>
+
+  This will put the FFmpeg sources into the directory <target>.
+
+    git clone git@git.videolan.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
+
+  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] <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://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 <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>
+
+  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 <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 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 <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.
+
+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.
+
+Contact the project admins <root at ffmpeg dot org> if you have technical
+problems with the GIT server.