Basic Git usage

Getting VLC source code via Git

$ git clone git://git.videolan.org/vlc.git

Voilà! The full VLC history should be on your hard disk in vlc/.

You can also clone using http with out repo.or.cz mirror.

$ git clone http://repo.or.cz/r/vlc.git

$ git log

to see the full log of the trunk.

$ gitk

to see the log graphically.

You can also browse the sources via gitweb.

Note for Windows users using Cygwin (linux-like build environment):

Applies to:

Windows XP Service Pack 2 with Security Update KB925902 installed
Windows XP Service Pack 3

There is a problem on Windows XP (and possibly on other Microsoft Operating Systems) with 'git clone' which aborts unexpectedly with a Cygwin error during the 'checking out files' (reproducable every time and at the same percentage) at the end of the clone procedure:

$ 2 [main] git 4012 D:\cygwin\bin\git.exe:
  *** fatal error - could not load shell32, Win32 error 487

This has been verified (May 22, 2008) against the currently available Cygwin 1.5.25-12 with git package versions 1.5.5.1-1 and 1.5.4-1 and is a generic problem which also affects cloning from other git repositories (although x264.git seems unaffected).

The issue is referred to in the mail archives of the Cygwin project mailing list here Git error on Cygwin.

By eliminating the impossible, whatever remained, however improbable, it is the following Windows Security Update (April 3, 2007) which is actually the cause of the Cygwin issue: Microsoft Security Bulletin MS07-017 - Vulnerabilities in GDI Could Allow Remote Code Execution (925902)

Even though the same Security Update applies to the following systems, these are reported not to be affected:

Windows Vista Service Pack 1
Windows 2003 Server Standard Service Pack 2

It is possible to get 'git clone' working again on the affected systems by removing the Security Update (KB925902) but this is obviously not recommended for security reasons.

Configure your global git config

Personal Information

Tell git your name. (use mostly by git-commit)

$ git config --global user.name "Your Name"
$ git config --global user.email "me@example.com"

Using git with color (Tip)

If you want to use git with colored output use:

$ git config --global color.ui true

If you are using an old git version (prior to 1.5.5) and previous command didn't work, use:

$ git config --global color.diff auto
$ git config --global color.status auto
$ git config --global color.branch auto

Setting up "git up" (Tip)

If you want to be able to just keep in sync using "git up" use:

$ git config --global alias.up "pull --rebase"

And if you like your tree to be messy and don't want git to complain (like in svn) use:

$ git config --global alias.up '!sh -c "git stash && git pull --rebase && git stash apply"'

Setting up "git wu" (Git What's Up) (Tip)

If you want to see what you are about to "git push":

$ git config --global alias.wu "log --stat origin..@{0}"

Now use:

$ git wu

Setting up "git wup" (Git What's Up - with patch) (Tip)

If you want to see what you are about to "git push", along with the diff:

$ git config --global alias.wup "log -p origin..@{0}"

Now use:

$ git wup

General GIT Workflow

1. Make your file edits in your local repository.

2. "git commit" the changes in your local repository

3. "git pull --rebase" or "git up" (if you did git config --global alias.up "pull --rebase") to bring the rest of your local repository up to date

4. "git log origin..master" to check what you are going to commit

4. "git push" to move your changes up to the master

"git stash" if you want to "hide" your changes. Do this if you think there may be other commits against ther same things you are working on, want to refresh yourself (using a git pull --rebase) from the master. Use "git stash apply" to get your stash back.

"git checkout -f master" if you think your tree is pretty hopeless, need a kill-and-fill to bring the master into your local repository.

List the local branch

You can now list your local branch by doing

$ git branch

which should ouput

$ git branch
* master

List your local non committed changes

$ git status | less

Commit

Now you can start to work on your tree. As soon as you feel you've reached a step in developement you can commit locally your work by

$ git commit -a

or

$ git commit <specific files>

List your commits

$ git log

Keeping your local working branch in sync

$ git pull --rebase

To shorten up that command type

$ git config --global alias.up "pull --rebase"

Now you can just type:

$ git up

Use a graphical interface

$ gitk          # Tree Browser
$ qgit          # Tree Browser
$ git-gui       # Commit/push/... editor

Submitting patches to the vlc-devel

First make sure you have read our Sending Patches page. And that you've read the Check List.

If you have been developing on vlc locally and (still) don't have write access, you can submit all your commit in one shot using:

$ rm -Rf patches
$ git format-patch -o patches origin
$ git-send-email --to vlc-devel@videolan.org patches

If you have multiple patch consider using:

$ git-send-email --compose --no-chain-reply-to --to vlc-devel@videolan.org patches

which will produce the patches for each local commit in the directory "patches" and send them. --no-chain-reply-to make sure it doesn't reply do

[PATCH 0/m]
- [PATCH 1/m]
  - [PATCH 2/m]
    - ...

But :

[PATCH 0/m]
- [PATCH 1/m]
- [PATCH 2/m]
- ..

Advanced usage

Creating a secondary local branch

If you want to work on a specific project that could require a branch of the trunk, create a local branch of the current branch by doing:

$ git branch mywork

and to actually use it do:

$ git checkout mywork

Which could be summarized by:

$ git checkout -b mywork

Then do some commit on it... And you can go back to your original master branch by doing:

$ git checkout master

Fetching a remote branch

To see the remote branch use:

$ git branch -r

If the remote branch is named 0.8.6-bugfix

$ git branch 0.8.6-bugfix origin/0.8.6-bugfix 
Branch 0.8.6-bugfix set up to track remote branch refs/remotes/origin/0.8.6-bugfix.
$ git branch
 0.8.6-bugfix
 * master

To checkout that branch use:

$ git checkout 0.8.6-bugfix

To stay up-to-date a simple

$ git pull --rebase

Should be enough.

If warnings appear that files still need updating:

$ include/libvlc_internal.h: needs update
  include/mediacontrol_internal.h: needs update
  include/vlc/libvlc.h: needs update
  include/vlc_update.h: needs update
  modules/access/mms/mms.c: needs update
  ...

Then do a checkout -f to revert non committed local changes

$ git checkout -f

To stay up-to-date another

$ git pull --rebase

Should give no more warnings.

To push to the remote branch, use:

$git push origin 0.8.6-bugfix:0.8.6-bugfix

Creating a remote branch

If the new remote branch is named 0.9.0-bugfix, and is based on the local master branch. First make sure everything go as planned with the --dry-run option:

$ git push --dry-run origin master:refs/heads/0.9.0-stable
To git@git.videolan.org:vlc.git
* [new branch]      master -> 0.9.0-stable

Then push it:

$ git push origin master:refs/heads/0.9.0-stable
To git@git.videolan.org:vlc.git
* [new branch]      master -> 0.9.0-stable
$ git branch -r
 origin/0.9.0-stable
 origin/master

To checkout that branch now see Fetching a remote branch

Publishing your own fork

Goto http://repo.or.cz/w/vlc.git and click fork. You will be able to publish your work there.

Please don't forget to send a mail to the vlc-devel as soon as you create your fork.

Revert your non-committed local changes

$ git checkout -f

Edit or undo not yet pushed commits

This will undo the last commit

$ git reset HEAD^

which is the same as

$ git reset master^

(if you are checked-out copy of your tree is master) And also the same as

$ git reset a44a594 # note that there is no need to use the full sha id

If you have a stack of patch that you have not yet committed you can delete one patch from the list using git rebase --interactive

$ git rebase --interactive origin
 pick eacf185 test
 pick 56322eb VLMA owner is vlma prod.

 # Rebase 826757e..56322eb onto 826757e
 #
 # Commands:
 #  pick = use commit
 #  edit = use commit, but stop for amending
 #  squash = use commit, but meld into previous commit

Diff-ing

You can diff between two branches using

$ git diff branch1 branch2

You can diff between the previous 10th commit and current using

$ git diff HEAD~10 HEAD

You can diff between the previous 10th commit and current of the branch "mywork" using

$ git diff mywork~10 mywork

Imagine that git log is like

$ git log
commit e0394f269305edd09843257e7c1d1a66aaf48ab3
Author: jb <jb>
Date:   Fri Apr 13 07:14:48 2007 +0000
   qt4 - Mousewheel (2)
commit e80b339081aa6755f67c9bd8e2aacf93a9a79d95
[..]
commit ff7004b70fd239e4120deb160e2991bd5237b8df
[..]
commit a44a594898f981a145cfcace5f16f8973f9eb46f
[..]
commit 690df705c963cf6bf6f5746d54bc97a85ff91919
[..]
commit 679f8b1c3e0baa469efa970588b95a625c595d64
[..]

$ git diff a44a594898f981a145cfcace5f16f8973f9eb46f~2 e80b339081aa6755f67c9bd8e2aacf93a9a79d95

Will be equivalent to:

$ git diff ff7004b70fd239e4120deb160e2991bd5237b8df e80b339081aa6755f67c9bd8e2aacf93a9a79d95

And to:

$ git diff HEAD~4 HEAD^

Remember that to produce a patch you should rather use git-format-patch than git-diff most of the time.

Tracking regression

git has a great tool called git-bisect to help you to track a faulty commit. Imagine you are tracking a bug that is known to appear after 0.8.6 (assuming 0.8.6 is tagged):

$ git bisect start
$ git bisect bad # tell git current version has the bug you are tracking
$ git bisect good 0.8.6 # tell git 0.8.6 didn't has the bug

And then git will checkout a certain revision, and ask you to test it. And you simply say whether this version has the bug. If it has the bug:

$ git bisect bad

if the bug is not present:

$ git bisect good

And so on by bisection... At the end git will indicate the faulty commit. Most of the time this tool is really efficient to track regression.

If you can provide a script that test the presence of the bug

$ git bisect run <script_name>

will be able to track down the regression by itself. See git-bisect Documentation.

Using Git to push to VideoLAN git

Initial requirement

Make sure you've set your name and email in your commits

$ git config --global user.name "Your Name"
$ git config --global user.email "me@example.com"

Convert your tree to use your ssh push commit access

$ vi vlc/.git/config

And replace git://git.videolan.org/vlc.git by git@git.videolan.org:vlc.git

Staying up to date

 $ git pull --rebase

If you don't want to have to type --rebase everytime you pull do:

$ git config branch.master.rebase true

This one creates a merge object which is not how SVN worked, so let's use the first version...

 $ git pull

Pushing your work

 $ git log origin..master     # Check what you are going to push
 $ git push

Documentation about git

Git

Contents