123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415 |
- \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 one 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.
|