Git
Version 15 (Vadim Pisarevsky, 2013-10-03 05:50 am) → Version 16/24 (Vadim Pisarevsky, 2013-10-03 05:50 am)
h1. 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.
h2. Installing Git
* Windows users: take msysgit from http://code.google.com/p/msysgit/downloads/list. Also install "TortoiseGit":http://code.google.com/p/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":http://www.syntevo.com/smartgithg/index.html 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":http://www.sourcetreeapp.com/ as a very good GUI client.
h2. 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
<pre>git clone https://github.com/<username>/opencv.git</pre>
where <username> is your login at github.
[[How to contribute]]
* Download and install the GUI for Git. There are two popular alternatives:
If you use Ubuntu
If you're one of OpenCV users who want to work directly with the source code, but not one of core developers (i.e. you don't work at Itseez or Willow Garage), we recommend you to fork the OpenCV at the github: https://github.com/Itseez/opencv. This project is always up-to-date, and it is very convenient way to work with OpenCV sources, because all the github features are available for you! This will also allow you to later provide pull requests, so your developments may be added to the OpenCV master. Please refer to the github instructions on "forking the repo":https://help.github.com/articles/fork-a-repo.
But if you really want to make a contribution to the OpenCV, please study the [[Core developer guide|guidelines]], because only the high-quality code is merged to the master branch!
h1. Instruction for core developers
h2. Configuring Get the current OpenCV source code, by cloning the OpenCV git repository
Use any Git client (such as the "git" command-line tool, or a GUI tool such as "Git Extensions":http://sourceforge.net/projects/gitextensions/ (Windows), "TortoiseGit":http://code.google.com/p/tortoisegit/ (Windows), "SourceTree":http://www.sourcetreeapp.com/ (Mac), or gitk and git-gui (Linux).
* Main repository (enough for most OpenCV users)
<pre>git clone git://code.opencv.org/opencv.git</pre>
* Additional repository that contains auxiliary stuff, like big datasets for running the OpenCV tests
<pre>git clone git://code.opencv.org/opencv_extra.git</pre>
That's it! Now you're ready to work directly with OpenCV sources.
h2. Contributing to the project
*Please note that the steps below are for core developers only! If you're not one of them , please consider making "pull requests":https://github.com/Itseez/opencv/pulls at the github. But if you work at Itseez or Willow, please continue.*
h3. Instruction for Ubuntu users:
* Upload ssh-key to the server. If you haven't created any, do it with the following command: <pre>ssh-keygen -t rsa -f ~/.ssh/id_rsa</pre> 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 <pre>ssh-add ~/.ssh/id_rsa</pre> 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
<pre>git remote set-url origin --push [email protected]:opencv.git</pre>
h3. 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 <pre>ssh-keygen -t rsa -C "[email protected]"</pre> 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: <pre>git remote set-url origin --push [email protected]:opencv.git</pre> 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.
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.
h2. Installing Git
* Windows users: take msysgit from http://code.google.com/p/msysgit/downloads/list. Also install "TortoiseGit":http://code.google.com/p/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":http://www.syntevo.com/smartgithg/index.html 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":http://www.sourcetreeapp.com/ as a very good GUI client.
h2. 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
<pre>git clone https://github.com/<username>/opencv.git</pre>
where <username> is your login at github.
[[How to contribute]]
* Download and install the GUI for Git. There are two popular alternatives:
If you use Ubuntu
If you're one of OpenCV users who want to work directly with the source code, but not one of core developers (i.e. you don't work at Itseez or Willow Garage), we recommend you to fork the OpenCV at the github: https://github.com/Itseez/opencv. This project is always up-to-date, and it is very convenient way to work with OpenCV sources, because all the github features are available for you! This will also allow you to later provide pull requests, so your developments may be added to the OpenCV master. Please refer to the github instructions on "forking the repo":https://help.github.com/articles/fork-a-repo.
But if you really want to make a contribution to the OpenCV, please study the [[Core developer guide|guidelines]], because only the high-quality code is merged to the master branch!
h1. Instruction for core developers
h2. Configuring Get the current OpenCV source code, by cloning the OpenCV git repository
Use any Git client (such as the "git" command-line tool, or a GUI tool such as "Git Extensions":http://sourceforge.net/projects/gitextensions/ (Windows), "TortoiseGit":http://code.google.com/p/tortoisegit/ (Windows), "SourceTree":http://www.sourcetreeapp.com/ (Mac), or gitk and git-gui (Linux).
* Main repository (enough for most OpenCV users)
<pre>git clone git://code.opencv.org/opencv.git</pre>
* Additional repository that contains auxiliary stuff, like big datasets for running the OpenCV tests
<pre>git clone git://code.opencv.org/opencv_extra.git</pre>
That's it! Now you're ready to work directly with OpenCV sources.
h2. Contributing to the project
*Please note that the steps below are for core developers only! If you're not one of them , please consider making "pull requests":https://github.com/Itseez/opencv/pulls at the github. But if you work at Itseez or Willow, please continue.*
h3. Instruction for Ubuntu users:
* Upload ssh-key to the server. If you haven't created any, do it with the following command: <pre>ssh-keygen -t rsa -f ~/.ssh/id_rsa</pre> 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 <pre>ssh-add ~/.ssh/id_rsa</pre> 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
<pre>git remote set-url origin --push [email protected]:opencv.git</pre>
h3. 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 <pre>ssh-keygen -t rsa -C "[email protected]"</pre> 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: <pre>git remote set-url origin --push [email protected]:opencv.git</pre> 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.