Git in a Bit!

Working with Git for the first time in opensource can indeed be overwhelming! The purpose of this blog post is to make that experience a little less troublesome by covering some of the initial steps which every novice should find useful. Its pretty concise for a topic as elaborate as git, yet I try to cover as many bits as I can  The following finds it’s origin in my notes for Git and GitHub while I was scaling my first steps into the world of collaborative development.

Git && Github ~ What’s difference ? Don’t they sound the same??

While Git is a revision control system, a tool to manage your source code history,  GitHub is a hosting service for Git repositories.  So, they are not the same thing: Git the tool, GitHub the service for projects that uses Git.

Ok , Good so which one do I use?

There are usually 2 types of patches one needs to contribute with opensource (my experience is largely composed of gnome) :

First, are the ones wherein your project has a repo hosted not on GitHub but (say)  Gnome Repos for existing Projects .

In this case you don’t really have to worry about the GitHub part of this post (unless of course you want to learn it anyways ).Here the git commands you would be looking for are (In order):

• git clone <git-url-for-project-repo> : This command will create a copy of the repository you intend to work on in your local system (the first time). It is this repo you will be working on to test the changes you will later want to contribute in the codebase. 
• If you already have a repo cloned then :

git fetch: This command updates your local copy of a remote branch. This operation never changes any of your own branches and is safe to do without changing your working copy.
git pull : This command does a “git fetch” followed by a “git merge” .It is what you would do to bring your repository up to date with a remote repository.

• git add <name-of-file-edited-by-you> : This command “updates the index using the current content found in the working tree, to prepare the content staged for the next commit”, it also ensures that the ignored files are not added by default.

Yeah, sounds fancy, BUT , how do I check if some file is added or not at any point of time in my git repo ?

    git status is what you want to run here .

That shows me the file I added , I need to see the changes too, is git that smart ?

Turns out , it is .. git diff  is what you are looking for here.

Continuing with the bullet flow..

• git commit -m “<commit-message>” : This command records the changes in the files earlier indexed(staged) to be “committed” into the history of the git repo.

Thus, you will use git add to start tracking new files and also to stage changes to already tracked files, then git status and git diff to see what has been modified and staged and finally git commit to record your snapshot into your history

So, I have the changes here, they work like pretty and I am proud of me . but, how do they get to the parent repo?!

Here is when we introduce patches. These are consolidated pieces of code you would attach to Bug reports in (here Bugzilla) or send to mailing lists to share the modifications you have with you in your local repo, and the ones which you would like to be integrated into the main source code of the respective projects.

• git format-patch HEAD^ : This command generates patches suitable for being applied via “git am” , In the scope of this blog, I only describe the command given the one commit on a clean repo is being patched.

Thus, with the above workflow , you will find that you have successfully leaped the first baby steps towards git. I’d highly recommend going through branching and many more concepts which can be found in a great reference -> HERE

Thanks for the first way round , but too bad, I have a project which requires me to issue PRs (whatever they are ! )

Second kind of projects are those which are hosted on the web and have repositories in GitHub (for eg gnome-music )

While the first steps until committing changes in these are the same, the way a developer is required to communicate these changes to the co-developers varies a bit. After “git commit” , the workflow derails to the following steps:

if you have rights to change the master project repo (which is a little unlikely if you find this blog useful ):  then directly use “git push“

if not: you need to do the following :

• Go to the “Fork” option on the extreme right of the webpage of the git repo and fork it
• A copy of the repo in your github page gets created. This is where you will need to merge the changes from your local copy for you to request a pull request with the master repo of the respective project. The URL for this will be referred to as <your-project-fork-url> in the subsequent post.
• Since a direct command to push into the master wont work , we need to first push it into our repo on Github and then request the maintainers to merge the changes with the project repo.
• git remote add <remote-name> <your-project-fork-url> : This command will add another repository for the main repo to synchronize with.
• git push <remote-name> master: This command pushes the required changes to your forked repository.

So far so good, but where are the PRs!! (Pull Requests)

The final step involves going to the main project page. In the right side column of the page is an option called “Pull Requests” , click it  < Click on the green button on top-right which says “New pull request” < select the base repo on the left-side (i.e. the project repo) and your project repo on the right < The required git diff is generated < Click “Send Pull Request”

(While choosing the repos you want to compare, one can choose other repositories other than just the master for the given repo. Thankfully the github ui is friendly enough to walk newbies through this !)

Voila ! there you go, bug the people on the channel to make sure your enhancements are merged

Other advanced tools you might want to look at – git rebase, git gui, git mergetool, git branch, git stash, git fetch, git pull,git merge (and more as you go ) Hope it helps in “un-horrifying” the initial troubles with git and github.

Signing off :“Its not that I know too much, its only that I know what hitting the “?” key on any page in Github does  ”

~ Shivani Poddar