From 150c9823e71a161e97003849cf8b2f55b21520bd Mon Sep 17 00:00:00 2001
From: Tim Redfern <tim@eclectronics.org>
Date: Mon, 26 Aug 2013 15:10:18 +0100
Subject: adding ffmpeg specific version

---
 ffmpeg1/doc/git-howto.texi | 415 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 415 insertions(+)
 create mode 100644 ffmpeg1/doc/git-howto.texi

(limited to 'ffmpeg1/doc/git-howto.texi')

diff --git a/ffmpeg1/doc/git-howto.texi b/ffmpeg1/doc/git-howto.texi
new file mode 100644
index 0000000..44e1cc6
--- /dev/null
+++ b/ffmpeg1/doc/git-howto.texi
@@ -0,0 +1,415 @@
+\input texinfo @c -*- texinfo -*-
+
+@settitle Using git to develop FFmpeg
+
+@titlepage
+@center @titlefont{Using git to develop FFmpeg}
+@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 FFmpeg-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://source.ffmpeg.org/ffmpeg <target>
+@end example
+
+This will put the FFmpeg sources into the directory @var{<target>}.
+
+@example
+git clone git@@source.ffmpeg.org:ffmpeg <target>
+@end example
+
+This will put the FFmpeg sources into the directory @var{<target>} and let
+you push back your changes to the remote repository.
+
+Make sure that you do not have Windows line endings in your checkouts,
+otherwise you may experience spurious compilation failures. One way to
+achieve this is to run
+
+@example
+git config --global core.autocrlf false
+@end example
+
+
+@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
+@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
+FFmpeg'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://source.ffmpeg.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 Git configuration
+
+In order to simplify a few workflows, it is advisable to configure both
+your personal Git installation and your local FFmpeg repository.
+
+@section Personal Git installation
+
+Add the following to your @file{~/.gitconfig} to help @command{git send-email}
+and @command{git format-patch} detect renames:
+
+@example
+[diff]
+        renames = copy
+@end example
+
+@section Repository configuration
+
+In order to have @command{git send-email} automatically send patches
+to the ffmpeg-devel mailing list, add the following stanza
+to @file{/path/to/ffmpeg/repository/.git/config}:
+
+@example
+[sendemail]
+        to = ffmpeg-devel@@ffmpeg.org
+@end example
+
+@chapter FFmpeg 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 pre-push checklist
+
+Once you have a set of commits that you feel are ready for pushing,
+work through the following checklist to doublecheck everything is in
+proper order. This list tries to be exhaustive. In case you are just
+pushing a typo in a comment, some of the steps may be unnecessary.
+Apply your common sense, but if in doubt, err on the side of caution.
+
+First, make sure that the commits and branches you are going to push
+match what you want pushed and that nothing is missing, extraneous or
+wrong. You can see what will be pushed by running the git push command
+with --dry-run first. And then inspecting the commits listed with
+@command{git log -p 1234567..987654}. The @command{git status} command
+may help in finding local changes that have been forgotten to be added.
+
+Next let the code pass through a full run of our testsuite.
+
+@itemize
+@item @command{make distclean}
+@item @command{/path/to/ffmpeg/configure}
+@item @command{make check}
+@item if fate fails due to missing samples run @command{make fate-rsync} and retry
+@end itemize
+
+Make sure all your changes have been checked before pushing them, the
+testsuite only checks against regressions and that only to some extend. It does
+obviously not check newly added features/code to be working unless you have
+added a test for that (which is recommended).
+
+Also note that every single commit should pass the test suite, not just
+the result of a series of patches.
+
+Once everything passed, push the changes to your public ffmpeg clone and post a
+merge request to ffmpeg-devel. You can also push them directly but this is not
+recommended.
+
+@chapter Server Issues
+
+Contact the project admins @email{root@@ffmpeg.org} if you have technical
+problems with the GIT server.
-- 
cgit v1.2.3