paulbouwer.com

I have used the open source enterprise search platform Solr for a number of years now and on a recent project have been using the open source SolrNet .NET client library. The SolrNet library lacked a feature I required when used with the bundled Service Locator implementation. A number of people had been asking for the same feature so I decided to jump in and implement it.

This is part 4 of my journey into learning Git, using GitHub and contributing to an open source project.

• Introduction
• Part 1 – Install Git
• Part 2 – Set up GitHub
• Part 3 – Fork project
• Part 4 – Contribute code
• Part 5 – Submit pull request

The feature

The feature in SolrNet that I was interested in updating revolved around using the built in Service Locator to support multi-tenancy.

No one had volunteered their time to implement this feature as can be seen by a thread in the SolrNet Google Group, so I decided to jump in and implement the feature.

Committing the implemented feature

After implementing the feature I was ready to commit my code to my local repository which was located in my C:\Projects\GitHub\SolrNet folder. I ran the git status command via the Git Bash shell. This will show any new files that I have created or any changes to existing files that I have made.

git status

The Changed but not updated list refers to files that have been modified in the working directory but have not yet been staged. The Untracked files list refers to new files in the working directory that Git does not have in a previous snapshot (commit). All these files need to be added to the staging area in preparation for the commit.

The staging area is where changes can be grouped before being committed. This gives you a lot of flexibility in what actually goes into a commit. There is a nice explanation on the git ready site.

I ran the git add command via the Git Bash shell for each of the files that I needed to add to the staging area.

git add

I then ran the git status command via the Git Bash shell again to confirm that the files were now all in the staging area of my local repository.

I ran the git commit command via the Git Bash shell to commit the changes from the staging area. The -m switch allows you to specify the commit message. I used the issue details Issue 83: Support for multi core using ServiceLocator as my commit message.

git commit -m

I ran the git status command again via the Git Bash shell again to confirm that all staged changes had been committed in my local repository.

Pushing commits to public repository

You may have noticed the following message in the last screenshot: Your branch is ahead of ‘origin/master’ by 1 commit. This is showing that my local repository now has a commit that is not in my public paulbouwer/SolrNet repository. To confirm that the name origin references my public paulbouwer/SolrNet repository I ran the git remote command via the Git Bash shell. The -v switch switches on verbose messages and the show -n action and switch specifies the name of the remote.

git remote -v show -n

I next ran the git push command via the Git Bash shell to push my commit to my public paulbouwer/SolrNet repository on GitHub. I am pushing my local changes to the master branch on my origin remote. Note that the password here is not your passphrase but your GitHub account password.

git push

A final git status command via the Git Bash shell confirms that my local branch is no longer out of sync with my public paulbouwer/SolrNet repository on GitHub.

Confirmation

The commit pushed up to my public paulbouwer/SolrNet repository on GitHub is clearly visible under the Commits tab. Clicking on the commit hyperlink for the commit will take you to the details of the commit.

Next is submitting a pull request and getting the code accepted into the master repository …

I have used the open source enterprise search platform Solr for a number of years now and on a recent project have been using the open source SolrNet .NET client library. The SolrNet library lacked a feature I required when used with the bundled Service Locator implementation. A number of people had been asking for the same feature so I decided to jump in and implement it.

This is part 3 of my journey into learning Git, using GitHub and contributing to an open source project.

• Introduction
• Part 1 – Install Git
• Part 2 – Set up GitHub
• Part 3 – Fork project
• Part 4 – Contribute code
• Part 5 – Submit pull request

Configure Git Options

Since I was about to fork a project and start dealing with code it seems like a good time to configure my identity within Git. Git uses your name and email address to sign your commits.

This can be achieved via the Git Bash shell by typing the following commands:

git config --global user.name "your_full_name" git config --global user.email "your_email_address"

The global switch applies this information to all of your projects. If you would like to override options for a particular project leave out the –global switch when in that project.

The following command will list out all your configured options:

git config --list

GitHub Workflow

The typical workflow of contributors to an open source project hosted on GitHub can be a bit intimidating. It involves the following steps:

• Fork
• Clone
• Write and commit code
• Push
• Submit pull request

I’ll discuss the first two steps (fork, clone) in this post and will cover the remainder in the next two posts.

Forking the SolrNet Project

The SolrNet project was created by Mauricio Scheffer and is hosted on GitHub at https://github.com/mausch/SolrNet.

To contribute code to a project on GitHub typically starts with you having to fork the project. Forking the project creates a copy of the master repository with a complete history under your GitHub account. This is great since it allows you to start contributing code and have the changes publically available to anyone who wants them – you don’t need commit access to the master project.

I navigated to the master project mausch/SolrNet page and clicked on the Fork button.

GitHub managed the forking of the master project and created a forked copy for me. It is now available at https://github.com/paulbouwer/SolrNet. GitHub also clearly shows that the project has been forked from the original project mausch/SolrNet.

Git is a distributed version control system which allows greater flexibility in how developers contribute and collaborate on projects. I don’t have commit access to the master repository mausch/SolrNet so GitHub helped me fork the repository to create a public repository paulbouwer/SolrNet to which I have read/commit access. So now I can commit changes into my paulbouwer/SolrNet repository and Mauricio can pull any of my commits into the master mausch/SolrNet repository (if he wants them).

Cloning your GitHub repository

A typical and common workflow in Git is to have a private local copy of your public repository. This allows you to have a working space that is under revision control. Once you are happy with the changes you have implemented you can roll them up into a single commit to your public repository and ask the maintainer of the master project to pull your commit into the master repository.

Obtaining a private local copy of your public repository is achieved using the git clone command. As the name suggests this is a clone of the repository (as opposed to a checkout in SVN). The cloned repository contains its own copy of the entire history of the project.

First we need the public repository URL from GitHub. I was having some firewall issues with SSH so decided to use my HTTP URL.

I ran the git clone command from the C:\Projects\GitHub folder via Git Bash shell. When prompted for a password enter the key passphrase for the SSH key registered with GitHub.

git clone https://paulbouwer@github.com/paulbouwer/SolrNet.git

This successfully cloned my public paulbouwer/SolrNet repository into my C:\Projects\GitHub\SolrNet folder as can be seen above. You can also see that the master branch is the active branch at the moment.

You can also clone a repository via TortoiseGit by clicking on Git Clone … on the right click context menu in Windows Explorer in the C:\Projects\GitHub folder.

After providing your SSH key passphrase TortoiseGit will begin the clone.

TortoiseGit has successfully cloned my public paulbouwer/SolrNet repository into my C:\Projects\GitHub\SolrNet folder as can be seen above. This is missing some of the contextual information we saw in the Git Bash shell such as the current active branch. I prefer using the Git Bash shell as it gives me more information and finer grained control. I will continue purely with the Git Bash shell for the rest of this series of posts.

Adding remotes

Now that I have a local copy of my repository I need a mechanism to manage changes between it and my public repository paulbouwer/SolrNet. I also need to manage changes between my local repository and the master repository mausch/SolrNet. This is achieved using the remotes concept in Git.

From the Working with Remotes section of the Pro Git book:

Remote repositories are versions of your project that are hosted on the Internet or network somewhere. You can have several of them, each of which generally is either read-only or read/write for you. Collaborating with others involves managing these remote repositories and pushing and pulling data to and from them when you need to share work

I obtained the HTTP URL of the master repository mausch/SolrNet.

I added a link to the master repository using the git remote command via the Git Bash shell. I used the typical remote name of upstream to denote the master repository mausch/SolrNet. I used the git remote command to also verify that the remote was added correctly.

git remote add upstream https://github.com/mausch/SolrNet.git git remote –v

The remote link to the master repository has been successfully added under the name upstream. But what is that remote named origin and how did it get added? When you clone a repository, Git automatically adds a remote to the repository you have cloned with the name of origin.

I then ran the git fetch command via the Git Bash shell. This fetches any changes from my upstream remote and pulls them down into my local repository. I did not do this for my origin remote since I know that I have just cloned my local repository from it.

git fetch upstream

The git fetch command fetches changes across all the available branches.

The final step is now to run the git merge command via the Git Bash shell. This will merge the fetched upstream changes into my local repository.

git merge upstream/master

I was only concerned about the master branch changes and therefore that is all that I merged in from the upstream fetch. You can also see that since I had just forked my public repository and cloned my local repository from that there were no changes to merge in.

Now I have a public repository that I can use for pull requests and an up to date local repository that is ready for me to start coding in. Next is writing some code …

I have used the open source enterprise search platform Solr for a number of years now and on a recent project have been using the open source SolrNet .NET client library. The SolrNet library lacked a feature I required when used with the bundled Service Locator implementation. A number of people had been asking for the same feature so I decided to jump in and implement it.

This is part 2 of my journey into learning Git, using GitHub and contributing to an open source project.

• Introduction
• Part 1 – Install Git
• Part 2 – Set up GitHub
• Part 3 – Fork project
• Part 4 – Contribute code
• Part 5 – Submit pull request

What is GitHub ?

GitHub is the popular web-based hosting service for projects that use the Git revision control system. It has a large number of project management, code hosting and community based features.

Sign up for GitHub

GitHub offers a free account for open source projects. This account has an unlimited number of public repositories and public collaborators. There are also plans that cater for private repositories and collaborators.

The source code for the SolrNet project is hosted on GitHub so I signed up for the free plan and created myself an account on GitHub.

Once you have updated the Public Profile and Email Addresses sections of your account you will notice that you need to associate an SSH public key with your GitHub account.

Generate an SSH key

Fire up the PuTTY Key Generator executable puttygen.exe found in the PuTTY install folder.

Select the SSH-2 RSA radio button and ensure that the number of bits is set to 1024. Click the Generate button to generate the public/private key pair.

Cryptography calls for unpredictable random numbers. A simple way to obtain this randomness is to generate it from the user. The PuTTY Key Generator uses random mouse movements to generate randomness.

Give the generated key a comment and provide a passphrase. The passphrase provides an extra layer of security for your key. This is not my actual key but even if it was – all that is visible here is my public key which is meant for public distribution anyway …

Create a .ssh folder in your home folder. I created a C:\Users\paul\.ssh folder. Save your public key into this folder by clicking on the Save public key button.

Save the private key into your .ssh folder by clicking on the Save private key button.

You should now have a public/private SSH key pair for GitHub. My public key is github_rsa and my private key is github_rsa.ppk. Never let anyone have access to your private key !

Add public key to GitHub

Now we are ready to add our newly generated public SSH key to GitHub. Highlight the text in the Public key text box and copy it to the clipboard (CTRL-C).

If you have already closed the PuTTY Key Generator I’ll show you how to load the key back up. Fire up the PuTTY Key Generator executable again and click on the Load button.

Select your GitHub private key file and click on the Open button.

You’ll be required to provide your passphrase to load the private key.

Now highlight the text in the public key text box and copy it to the clipboard (CTRL-C).

Go back to the SSH Public Key section in your GitHub account. Click on the Add another public key link.

Paste (CTRL-V) the public key from your clipboard into the Key text box. Provide a Title for your key and click on the Add key button.

GitHub is now set up with your SSH public key.

Next is forking the SolrNet project …

I have used the open source enterprise search platform Solr for a number of years now and on a recent project have been using the open source SolrNet .NET client library. The SolrNet library lacked a feature I required when used with the bundled Service Locator implementation. A number of people had been asking for the same feature so I decided to jump in and implement it.

This is part 1 of my journey into learning Git, using GitHub and contributing to an open source project.

• Introduction
• Part 1 – Install Git
• Part 2 – Set up GitHub
• Part 3 – Fork project
• Part 4 – Contribute code
• Part 5 – Submit pull request

What is Git ?

Git is a free and open source, distributed version control system initially designed and developed by Linus Torvalds of Linux fame. Even though there are fundamental differences from a revision control system such as Subversion, there are numerous books and documentation available to help you.

The major difference with Subversion is that every Git working directory is a full-fledged repository with complete history and full revision tracking capabilities, not dependent on network access or a central server. This takes some time to get used to but once the light comes on it is pretty cool.

Install PuTTY

If you want to use GitHub you’ll need an SSH key. Even though Git comes with an SSH client, I highly recommended that you install PuTTY on Windows. This is a free Telnet/SSH client that has a number of utilities that make dealing with SSH keys and passphrases more pleasant.

I downloaded and installed the PuTTY 0.60 Windows Installer.

Make sure that you associate .PPK (PuTTY Private Key) files with Pageant (SSH authentication agent) and PuTTYgen (SSH key generation utility).

Install Git

To install Git on Windows you need to download Git for Windows and install it. I downloaded and installed the full installer for official Git 1.7.3.1.

I was only interested in using the Git Bash shell via the Windows Explorer context menu and so selected the Git Bash Here option. Since I was installing TortoiseGit for GUI based Git interactions I did not want my context menu cluttered with the Git GUI Here option.

I selected the Use Git Bash only option here since I wanted my Git environment to work smoothly and remain contained. I was also only ever going to use command line Git from the Git Bash shell.

Since I have PuTTY and TortoiseSVN already installed the Git installer has picked up the various Plink.exe executables. Plink is a command line interface to the PuTTY libraries that tools such as Git or TortoiseSVN/TortoiseGit use to provide SSH capabilities.

I selected the Use (Tortoise)Plink option and made sure that the file path pointed to the Plink executable in my PuTTY install folder. Now Git will use PuTTY to manage its SSH requirements.

Git can translate line endings between Windows and Unix style line endings. I selected the Checkout as-is, commit as-is option as this would not perform any conversions. I figured that if I was working on a Windows project it should have Windows line endings.

Confirm that Git for Windows has been successfully installed by firing up the Git Bash shell. I fired mine up in my projects folder.

Install TortoiseGit

TortoiseGit provides an extension to Windows Explorer that works with a Git repository. Some people feel more comfortable using graphical tools. I prefer to have both since I can use whichever one helps me get a specific task done faster or easier.

I downloaded and installed the Tortoise Git 1.5.8.0 Windows installer.

Like Git, TortoiseGit also can be made to use the PuTTY Plink executable.

I selected all the features and completed the installation. That was easy !

Git enabled !

I now had Git installed and was equipped with both the command line Git Bash shell and GUI based TortoiseGit options.

Next is setting up GitHub …

I have used the open source enterprise search platform Solr for a number of years now and on a recent project have been using the open source SolrNet .NET client library. The SolrNet library lacked a feature I required when used with the bundled Service Locator implementation. A number of people had been asking for the same feature so I decided to jump in and implement it.

This is my journey into learning Git, using GitHub and contributing to an open source project. I highly recommend the experience – you learn a great deal from reading and contributing to code that is so highly visible.

I have split my journey into the following 5 parts:

• Part 1 – Install Git
• Part 2 – Set up GitHub
• Part 3 – Fork project
• Part 4 – Contribute code
• Part 5 – Submit pull request