1 Getting started with Git and Gerrit
2 ===================================
4 Overview of Git and Gerrit
5 --------------------------
7 Git is an opensource distributed version control system (dvcs) written
8 in the C language and originally developed by Linus Torvalds and others
9 to manage the Linux kernel. In Git, there is no central copy of the
10 repository. After you have cloned the repository, you have a functioning
11 copy of the source code with all the branches and tagged releases, in
12 your local repository.
14 Gerrit is an opensource web-based collaborative code review tool that
15 integrates with Git. It was developed at Google by Shawn Pearce. Gerrit
16 provides a framework for reviewing code commits before they are accepted
17 into the code base. Changes can be uploaded to Gerrit by any user.
18 However, the changes are not made a part of the project until a code
19 review is completed. Gerrit is also a good collaboration tool for
20 storing the conversations that occur around the code commits.
22 The OpenDaylight source code is hosted in a repository in Git.
23 Developers must use Gerrit to commit code to the OpenDaylight
28 For more information on Git, see http://git-scm.com/. For more
29 information on Gerrit, see https://code.google.com/p/gerrit/.
31 Setting up a Gerrit account
32 ---------------------------
34 1. Using a Google Chrome or Mozilla Firefox browser, go to
35 https://git.opendaylight.org/gerrit
37 The main page shows existing Gerrit requests. These are patches that
38 have been pushed to the repository and not yet verified, reviewed, and
43 If you already have an OpenDaylight account, you can click **Sign
44 In** in the top right corner of the page and follow the instructions
45 to enter the OpenDaylight page.
47 .. figure:: ./images/Sign_in.jpg
48 :alt: Signing in to OpenDaylight account
50 Signing in to OpenDaylight account
52 1. If you do not have an existing OpenDaylight account, click **Account
53 signup/management** on the top bar of the main Gerrit page.
55 The **WS02 Identity Server** page is displayed.
57 .. figure:: ./images/Gerrit_setup.jpg
58 :alt: Gerrit Account signup/management link
60 Gerrit Account signup/management link
62 1. In the **WS02 Identity Server** page, click **Sign-up** in the left
65 There is also an option to authenticate your sign in with OpenID. This
66 option is not described in this document.
68 .. figure:: ./images/sign-up.jpg
69 :alt: Sign-up link for Gerrit account
71 Sign-up link for Gerrit account
73 1. Click on the **Sign-up with User Name/Password** image on the right
74 pane to continue to the actual sign-up page.
76 .. figure:: ./images/signup_image.jpg
77 :alt: Sign-up with User Name/Password Image
79 Sign-up with User Name/Password Image
81 1. Fill out the details in the account creation form and then click
84 .. figure:: ./images/form_details.jpg
85 :alt: Filling out the details
87 Filling out the details
89 You now have an OpenDaylight account that can be used with Gerrit to
90 pull the OpenDaylight code.
92 Generating SSH keys for your system
93 -----------------------------------
95 You must have SSH keys for your system to register with your Gerrit
96 account. The method for generating SSH keys is different for different
97 types of operating systems.
99 The key you register with Gerrit must be identical to the one you will
100 use later to pull or edit the code. For example, if you have a
101 development VM which has a different UID login and keygen than that of
102 your laptop, the SSH key you generate for the VM is different from the
103 laptop. If you register the SSH key generated on your VM with Gerrit and
104 do not reuse it on your laptop when using Git on the laptop, the pull
109 For more information on SSH keys for Ubuntu, see
110 https://help.ubuntu.com/community/SSH/OpenSSH/Keys. For generating
111 SSH keys for Windows, see
112 https://help.github.com/articles/generating-ssh-keys.
114 For a system running Ubuntu operating system, follow the steps below:
116 1. Run the following command::
122 1. You are prompted for a location to save the keys, and a passphrase
125 This passphrase protects your private key while it is stored on the hard
126 drive. You must use the passphrase to use the keys every time you need
127 to login to a key-based system::
129 Generating public/private rsa key pair.
130 Enter file in which to save the key (/home/b/.ssh/id_rsa):
131 Enter passphrase (empty for no passphrase):
132 Enter same passphrase again:
133 Your identification has been saved in /home/b/.ssh/id_rsa.
134 Your public key has been saved in /home/b/.ssh/id_rsa.pub.
136 Your public key is now available as **.ssh/id\_rsa.pub** in your home
139 Registering your SSH key with Gerrit
140 ------------------------------------
142 1. Using a Google Chrome or Mozilla Firefox browser, go to
143 https://git.opendaylight.org/gerrit.
145 1. Click **Sign In** to access the OpenDaylight repository.
147 .. figure:: ./images/Sign_in.jpg
148 :alt: Signin in to OpenDaylight repository
150 Signin in to OpenDaylight repository
152 1. Click your name in the top right corner of the window and then click
155 The **Settings** page is displayed.
157 .. figure:: ./images/Gerrit_settings.jpg
158 :alt: Settings page for your Gerrit account
160 Settings page for your Gerrit account
162 1. Click **SSH Public Keys** under **Settings**.
164 2. Click **Add Key**.
166 3. In the **Add SSH Public Key** text box, paste the contents of your
167 **id\_rsa.pub** file and then click **Add**.
169 .. figure:: ./images/SSH_keys.jpg
170 :alt: Adding your SSH key
174 To verify your SSH key is working correctly, try using an SSH client to
175 connect to Gerrit’s SSHD port::
177 $ ssh -p 29418 <sshusername>@git.opendaylight.org
178 Enter passphrase for key '/home/cisco/.ssh/id_rsa':
179 **** Welcome to Gerrit Code Review ****
180 Hi <user>, you have successfully connected over SSH.
181 Unfortunately, interactive shells are disabled.
182 To clone a hosted Git repository, use: git clone ssh://<user>@git.opendaylight.org:29418/REPOSITORY_NAME.git
183 Connection to git.opendaylight.org closed.
185 You can now proceed to either Pulling, Hacking, and Pushing the Code
186 from the CLI or Pulling, Hacking, and Pushing the Code from Eclipse
187 depending on your implementation.