doc: port the git-howto to texinfo

doc/Makefile

@@ -5,6 +5,7 @@ HTMLPAGES   = $(PROGS-yes:%=doc/%.html)                                 \
               doc/faq.html                                              \
               doc/fate.html                                             \
               doc/general.html                                          \
+              doc/git-howto.html                                        \
               doc/libavfilter.html                                      \
 
 DOCS = $(HTMLPAGES) $(MANPAGES) $(PODPAGES)

doc/git-howto.texi

+\input texinfo @c -*- texinfo -*-
+
+@settitle Using git to develop Libav
+
+@titlepage
+@center @titlefont{Using git to develop Libav}
+@end titlepage
+
+@top
+
+@contents
+
+@chapter Introduction
+
+This document aims in giving some quick references on a set of useful git
+commands. You should always use the extensive and detailed documentation
+provided directly by git:
+
+@example
+git --help
+man git
+@end example
+
+shows you the available subcommands,
+
+@example
+git <command> --help
+man git-<command>
+@end example
+
+shows information about the subcommand <command>.
+
+Additional information could be found on the
+@url{http://gitref.org, Git Reference} website
+
+For more information about the Git project, visit the
+
+@url{http://git-scm.com/, Git website}
+
+Consult these resources whenever you have problems, they are quite exhaustive.
+
+What follows now is a basic introduction to Git and some Libav-specific
+guidelines to ease the contribution to the project
+
+@chapter Basics Usage
+
+@section Get GIT
+
+You can get git from @url{http://git-scm.com/}
+Most distribution and operating system provide a package for it.
+
+
+@section Cloning the source tree
+
+@example
+git clone git://git.libav.org/libav.git <target>
+@end example
+
+This will put the Libav sources into the directory @var{<target>}.
+
+@example
+git clone git@@git.libav.org:libav.git <target>
+@end example
+
+This will put the Libav sources into the directory @var{<target>} and let
+you push back your changes to the remote repository.
+
+
+@section Updating the source tree to the latest revision
+
+@example
+git pull (--rebase)
+@end example
+
+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.
+
+@float IMPORTANT
+Since merge commits are forbidden @command{--rebase} (see below) is recommended.
+@end float
+
+@section Rebasing your local branches
+
+@example
+git pull --rebase
+@end example
+
+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
+Libav's master tree. The master tree will reject pushes with merge commits.
+
+
+@section Adding/removing files/directories
+
+@example
+git add [-A] <filename/dirname>
+git rm [-r] <filename/dirname>
+@end example
+
+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.
+
+
+@section Showing modifications
+
+@example
+git diff <filename(s)>
+@end example
+
+will show all local modifications in your working directory as unified diff.
+
+
+@section Inspecting the changelog
+
+@example
+git log <filename(s)>
+@end example
+
+You may also use the graphical tools like gitview or gitk or the web
+interface available at http://git.libav.org/
+
+@section Checking source tree status
+
+@example
+git status
+@end example
+
+detects all the changes you made and lists what actions will be taken in case
+of a commit (additions, modifications, deletions, etc.).
+
+
+@section Committing
+
+@example
+git diff --check
+@end example
+
+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
+
+@example
+git diff -w -b <filename(s)>
+@end example
+
+Also check the output of
+
+@example
+git status
+@end example
+
+to make sure you don't have untracked files or deletions.
+
+@example
+git add [-i|-p|-A] <filenames/dirnames>
+@end example
+
+Make sure you have told git your name and email address
+
+@example
+git config --global user.name "My Name"
+git config --global user.email my@@email.invalid
+@end example
+
+Use @var{--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.
+
+
+@example
+git commit
+@end example
+
+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
+
+@example
+git config --global core.editor
+@end example
+
+or set by one of the following environment variables:
+@var{GIT_EDITOR}, @var{VISUAL} or @var{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.
+
+@section Preparing a patchset
+
+@example
+git format-patch <commit> [-o directory]
+@end example
+
+will generate a set of patches for each commit between @var{<commit>} and
+current @var{HEAD}. E.g.
+
+@example
+git format-patch origin/master
+@end example
+
+will generate patches for all commits on current branch which are not
+present in upstream.
+A useful shortcut is also
+
+@example
+git format-patch -n
+@end example
+
+which will generate patches from last @var{n} commits.
+By default the patches are created in the current directory.
+
+@section Sending patches for review
+
+@example
+git send-email <commit list|directory>
+@end example
+
+will send the patches created by @command{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. @var{git-email}
+package on Debian-based distros).
+
+
+@section Renaming/moving/copying files or contents of files
+
+Git automatically tracks such changes, making those normal commits.
+
+@example
+mv/cp path/file otherpath/otherfile
+git add [-A] .
+git commit
+@end example
+
+
+@chapter Libav specific
+
+@section Reverting broken commits
+
+@example
+git reset <commit>
+@end example
+
+@command{git reset} will uncommit the changes till @var{<commit>} rewriting
+the current branch history.
+
+@example
+git commit --amend
+@end example
+
+allows to amend the last commit details quickly.
+
+@example
+git rebase -i origin/master
+@end example
+
+will replay local commits over the main repository allowing to edit, merge
+or remove some of them in the process.
+
+@float NOTE
+@command{git reset}, @command{git commit --amend} and @command{git rebase}
+rewrite history, so you should use them ONLY on your local or topic branches.
+The main repository will reject those changes.
+@end float
+
+@example
+git revert <commit>
+@end example
+
+@command{git revert} will generate a revert commit. This will not make the
+faulty commit disappear from the history.
+
+@section Pushing changes to remote trees
+
+@example
+git push
+@end example
+
+Will push the changes to the default remote (@var{origin}).
+Git will prevent you from pushing changes if the local and remote trees are
+out of sync. Refer to and to sync the local tree.
+
+@example
+git remote add <name> <url>
+@end example
+
+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.
+
+@example
+git push <remote> <refspec>
+@end example
+
+Will push the changes to the @var{<remote>} repository.
+Omitting @var{<refspec>} makes @command{git push} update all the remote
+branches matching the local ones.
+
+@section Finding a specific svn revision
+
+Since version 1.7.1 git supports @var{:/foo} syntax for specifying commits
+based on a regular expression. see man gitrevisions
+
+@example
+git show :/'as revision 23456'
+@end example
+
+will show the svn changeset @var{r23456}. With older git versions searching in
+the @command{git log} output is the easiest option (especially if a pager with
+search capabilities is used).
+This commit can be checked out with
+
+@example
+git checkout -b svn_23456 :/'as revision 23456'
+@end example
+
+or for git < 1.7.1 with
+
+@example
+git checkout -b svn_23456 $SHA1
+@end example
+
+where @var{$SHA1} is the commit hash from the @command{git log} output.
+
+@chapter Server Issues
+
+Contact the project admins @email{git@@libav.org} if you have technical
+problems with the GIT server.