mirror of
https://github.com/pineappleEA/pineapple-src.git
synced 2024-12-05 14:18:25 -05:00
436 lines
12 KiB
Plaintext
Executable File
436 lines
12 KiB
Plaintext
Executable File
\input texinfo @c -*- texinfo -*-
|
|
@documentencoding UTF-8
|
|
|
|
@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.
|
|
|
|
@example
|
|
git clone gil@@ffmpeg.org:ffmpeg-web <target>
|
|
@end example
|
|
|
|
This will put the source of the FFmpeg website into the directory
|
|
@var{<target>} and let you push back your changes to the remote repository.
|
|
(Note that @var{gil} stands for GItoLite and is not a typo of @var{git}.)
|
|
|
|
If you don't have write-access to the ffmpeg-web repository, you can
|
|
create patches after making a read-only ffmpeg-web clone:
|
|
|
|
@example
|
|
git clone git://ffmpeg.org/ffmpeg-web <target>
|
|
@end example
|
|
|
|
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
|
|
|
|
|
|
@anchor{Updating the source tree to the latest revision}
|
|
@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 @command{gitview} or @command{gitk}
|
|
or the web interface available at @url{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 @option{--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 @command{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 origin master --dry-run
|
|
@end example
|
|
|
|
Will simulate a push of the local master branch to the default remote
|
|
(@var{origin}). And list which branches and ranges or commits would have been
|
|
pushed.
|
|
Git will prevent you from pushing changes if the local and remote trees are
|
|
out of sync. Refer to @ref{Updating the source tree to the latest revision}.
|
|
|
|
@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 @samp{:/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 @samp{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 @option{--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 test suite.
|
|
|
|
@itemize
|
|
@item @command{make distclean}
|
|
@item @command{/path/to/ffmpeg/configure}
|
|
@item @command{make fate}
|
|
@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
|
|
test suite 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 at @email{root@@ffmpeg.org} if you have technical
|
|
problems with the Git server.
|