273 lines
7.9 KiB
Plaintext
273 lines
7.9 KiB
Plaintext
|
|
About Git write access:
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Before everything else, you should know how to use GIT properly.
|
|
Luckily Git comes with excellent documentation.
|
|
|
|
git --help
|
|
man git
|
|
|
|
shows you the available subcommands,
|
|
|
|
git <command> --help
|
|
man git-<command>
|
|
|
|
shows information about the subcommand <command>.
|
|
|
|
The most comprehensive manual is the website Git Reference
|
|
|
|
http://gitref.org/
|
|
|
|
For more information about the Git project, visit
|
|
|
|
http://git-scm.com/
|
|
|
|
Consult these resources whenever you have problems, they are quite exhaustive.
|
|
|
|
You do not need a special username or password.
|
|
All you need is to provide a ssh public key to the Git server admin.
|
|
|
|
What follows now is a basic introduction to Git and some Libav-specific
|
|
guidelines. Read it at least once, if you are granted commit privileges to the
|
|
Libav project you are expected to be familiar with these rules.
|
|
|
|
|
|
|
|
I. BASICS:
|
|
==========
|
|
|
|
0. Get GIT:
|
|
|
|
You can get git from http://git-scm.com/
|
|
|
|
|
|
1. Cloning the source tree:
|
|
|
|
git clone git://git.libav.org/libav.git <target>
|
|
|
|
This will put the Libav sources into the directory <target>.
|
|
|
|
git clone git@git.libav.org:libav.git <target>
|
|
|
|
This will put the Libav sources into the directory <target> and let
|
|
you push back your changes to the remote repository.
|
|
|
|
|
|
2. Updating the source tree to the latest revision:
|
|
|
|
git pull (--ff-only)
|
|
|
|
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.
|
|
Caveat: Since merge commits are forbidden at least for the initial
|
|
months of git --ff-only or --rebase (see below) are recommended.
|
|
--ff-only will fail and not create merge commits if your branch
|
|
has diverged (has a different history) from the tracked branch.
|
|
|
|
2.a Rebasing your local branches:
|
|
|
|
git pull --rebase
|
|
|
|
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.
|
|
|
|
|
|
3. Adding/removing files/directories:
|
|
|
|
git add [-A] <filename/dirname>
|
|
git rm [-r] <filename/dirname>
|
|
|
|
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.
|
|
|
|
|
|
4. Showing modifications:
|
|
|
|
git diff <filename(s)>
|
|
|
|
will show all local modifications in your working directory as unified diff.
|
|
|
|
|
|
5. Inspecting the changelog:
|
|
|
|
git log <filename(s)>
|
|
|
|
You may also use the graphical tools like gitview or gitk or the web
|
|
interface available at http://git.libav.org/
|
|
|
|
6. Checking source tree status:
|
|
|
|
git status
|
|
|
|
detects all the changes you made and lists what actions will be taken in case
|
|
of a commit (additions, modifications, deletions, etc.).
|
|
|
|
|
|
7. Committing:
|
|
|
|
git diff --check
|
|
|
|
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
|
|
|
|
git diff -w -b <filename(s)>
|
|
|
|
Also check the output of
|
|
|
|
git status
|
|
|
|
to make sure you don't have untracked files or deletions.
|
|
|
|
git add [-i|-p|-A] <filenames/dirnames>
|
|
|
|
Make sure you have told git your name and email address, e.g. by running
|
|
git config --global user.name "My Name"
|
|
git config --global user.email my@email.invalid
|
|
(--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.
|
|
|
|
git commit
|
|
|
|
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
|
|
|
|
git config core.editor
|
|
|
|
or set by one of the following environment variables:
|
|
GIT_EDITOR, VISUAL or 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.
|
|
|
|
|
|
8. Renaming/moving/copying files or contents of files:
|
|
|
|
Git automatically tracks such changes, making those normal commits.
|
|
|
|
mv/cp path/file otherpath/otherfile
|
|
|
|
git add [-A] .
|
|
|
|
git commit
|
|
|
|
Do not move, rename or copy files of which you are not the maintainer without
|
|
discussing it on the mailing list first!
|
|
|
|
9. Reverting broken commits
|
|
|
|
git revert <commit>
|
|
|
|
git revert will generate a revert commit. This will not make the faulty
|
|
commit disappear from the history.
|
|
|
|
git reset <commit>
|
|
|
|
git reset will uncommit the changes till <commit> rewriting the current
|
|
branch history.
|
|
|
|
git commit --amend
|
|
|
|
allows to amend the last commit details quickly.
|
|
|
|
git rebase -i origin/master
|
|
|
|
will replay local commits over the main repository allowing to edit,
|
|
merge or remove some of them in the process.
|
|
|
|
Note that the reset, commit --amend and rebase rewrite history, so you
|
|
should use them ONLY on your local or topic branches.
|
|
|
|
The main repository will reject those changes.
|
|
|
|
10. Preparing a patchset.
|
|
|
|
git format-patch <commit> [-o directory]
|
|
|
|
will generate a set of patches for each commit between <commit> and
|
|
current HEAD. E.g.
|
|
|
|
git format-patch origin/master
|
|
|
|
will generate patches for all commits on current branch which are not
|
|
present in upstream.
|
|
A useful shortcut is also
|
|
|
|
git format-patch -n
|
|
|
|
which will generate patches from last n commits.
|
|
By default the patches are created in the current directory.
|
|
|
|
11. Sending patches for review
|
|
|
|
git send-email <commit list|directory>
|
|
|
|
will send the patches created by 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. git-email
|
|
package on Debian-based distros).
|
|
|
|
12. Pushing changes to remote trees
|
|
|
|
git push
|
|
|
|
Will push the changes to the default remote (origin).
|
|
Git will prevent you from pushing changes if the local and remote trees are
|
|
out of sync. Refer to 2 and 2.a to sync the local tree.
|
|
|
|
git remote add <name> <url>
|
|
|
|
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.
|
|
|
|
git push <remote> <refspec>
|
|
|
|
Will push the changes to the remote repository. Omitting refspec makes git
|
|
push update all the remote branches matching the local ones.
|
|
|
|
13. Finding a specific svn revision
|
|
|
|
Since version 1.7.1 git supports ':/foo' syntax for specifying commits
|
|
based on a regular expression. see man gitrevisions
|
|
|
|
git show :/'as revision 23456'
|
|
|
|
will show the svn changeset r23456. With older git versions searching in
|
|
the git log output is the easiest option (especially if a pager with
|
|
search capabilities is used).
|
|
This commit can be checked out with
|
|
|
|
git checkout -b svn_23456 :/'as revision 23456'
|
|
|
|
or for git < 1.7.1 with
|
|
|
|
git checkout -b svn_23456 $SHA1
|
|
|
|
where $SHA1 is the commit SHA1 from the 'git log' output.
|
|
|
|
|
|
Contact the project admins <git at libav dot org> if you have technical
|
|
problems with the GIT server.
|