diff options
Diffstat (limited to 'ffmpeg/doc/git-howto.texi')
| -rw-r--r-- | ffmpeg/doc/git-howto.texi | 415 |
1 files changed, 0 insertions, 415 deletions
diff --git a/ffmpeg/doc/git-howto.texi b/ffmpeg/doc/git-howto.texi deleted file mode 100644 index 44e1cc6..0000000 --- a/ffmpeg/doc/git-howto.texi +++ /dev/null @@ -1,415 +0,0 @@ -\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. |