Working with OpenCV git repository.¶

2. Foreword

Git (http://en.wikipedia.org/wiki/Git_(software)) is distributed source code management system, which we now use to develop OpenCV. Therefore, OpenCV developers and contributors should have git installed and learn at least some basics of it. Of course, in the case of a small patch one may simply create a ticket at http://code.opencv.org/projects/opencv/issues and attach the patch there, but our practice shows that going through the pull request mechanism (see How to contribute) is much more efficient and for that you need git.

Installing Git¶

• Windows users: take msysgit from http://code.google.com/p/msysgit/downloads/list. Also install TortoiseGit, a convenient git front-end, which integrates right into Windows Explorer
• Linux users: install command-line git utility using your package manager, e.g. "apt-get install git" on Ubuntu and Debian. You can use SmartGit as a GUI client. SmartGit is cross-platform, btw.
• Mac users: if you installed Xcode (which you will need anyway), you already have git. You can use SourceTree as a very good GUI client.

Using Git¶

Most developers and contributors should work with their personal copy (a fork) of OpenCV repository at GitHub and submit the changes via pull requests, as described at How to contribute. For example, if you use command-line git utility, you can clone the repository to your computer by running

git clone https://github.com/<username>/opencv.git

where <username> is your login at github.

Instruction for core developers¶

Most developers should just use github and submit pull requests with their changes. Below are the instructions for those 2-3 people who should be able to push changes (or rather merge the pull requests) to the main repository.

Configuring git¶

Instruction for Ubuntu users:¶

• Upload ssh-key to the server. If you haven't created any, do it with the following command:

  ssh-keygen -t rsa -f ~/.ssh/id_rsa

  Leave the Passphrase empty. Then copy contents of the file ~/.ssh/id_rsa.pub to the Key field on the http://code.opencv.org/my/account page. Press Create. Run

  ssh-add ~/.ssh/id_rsa

  command. It may be critical on some versions of Ubuntu.

• Clone the repository as described in the section above. Run the following command in local repository folder to be able to push changes

  git remote set-url origin --push [email protected]:opencv.git

Instruction for Windows users:¶

• Download and install an up-to-date version of msysgit from its official site: http://code.google.com/p/msysgit/downloads/list. There is also the portable version (PortableGit-1.7.11-preview20120710.7z), which you need only to unpack to get access to the console version of Git. Supposing that for some of us it could be quite enough.
• Download and install the GUI for Git. There are two popular alternatives:
  • TortoiseGit is free, open source (GPL v2). It can be downloaded from http://code.google.com/p/tortoisegit/downloads/list. It has different versions for 32 and 64 bit, so be careful. While installing, locate your msysgit (if it doesn't do that automatically) and choose OpenSSH... (Not PLink... Putty...!).
  • SmartGit is also free, but for non-commercial use only. Written in Java, which can be installed automatically if needed. SmartGit can be downloaded from: http://www.syntevo.com/smartgit/download.html?all=true. Portable Archive (includes JRE) is recomended for download. It only requires unpacking and locating msysgit on first launch.
• Generate SSH access key:
  • Launch Git Bash (file git-bash.bat in msysgit folder).
  • Run

    ssh-keygen -t rsa -C  "[email protected]"

    with the console. The output will contain information on where it stored the keys.
  • Go to that directory and open the public key (id_rsa.pub) with any text editor.
  • Copy contents of the file id_rsa.pub to the Key field on the http://code.opencv.org/my/account page. Press Create.
• Clone repository, using 'quick' read-only protocol (git://code.opencv.org/opencv.git).
• Launch Git Bash again and go to the folder that you've cloned the repository to ('.git' folder should have appeared there). Run the following command:

  git remote set-url origin --push [email protected]:opencv.git

  to be able to push changes to the repository.
• That's it. You may try making some changes to commit and push them for the test run.