Skip to content

Getting started with github

Ramprasad Saptharishi edited this page May 7, 2015 · 5 revisions

There are several tutorials for github that you can find online, but I am going to tailor this specifically towards contributing to this survey.

If you have never used git before, I would suggest you first install git, add your ssh key and go over this tutorial I wrote a while back.

Contributing to the repository

Creating a fork

Once you have set-up your ssh keys, you can start contributing to the repository. To do this, you first create your own copy of the repository. Go to the main page of the repository (https://github.com/dasarpmar/lowerbounds-survey/ ) and you would find a button on the top right called 'Fork':

Forking the repository

Once you click on that link, you should have your own fork of the repository.

Working on the fork

Now that you have your own copy, you can start working on your fork of the repository. I am assuming that you have 'git' installed on your computer. If this is your first time with git, you probably need to give it your name and email address (so that all changes that you make would have your name and email tagged with it). To do this, run the following two commands (after making appropriate changes of course!)

$ git config --global user.name "Arthur Vandaley"
$ git config --global user.email artvandaley@marinebiologist.com

Next, you clone the repository on your computer. You would be making the changes in your favourite editor, and you can keep pushing changes to github. When you go to your github fork, you should find a link that you use to clone.

Cloning the repository

Copy that url, and then go to your terminal and type:

$ git clone https://github.com/dasarpmar-test/lowerbounds-survey.git

This should create a folder on your computer with all the files in it. Now you can go ahead and start making edits.

Tracking changes via git

Let us not get very fancy with branches and all (but you should, eventually). For now, let us stick to the default master branch. General work flow is: Make a change -> git add the change -> git commit the change. Let me give you a working example with a silly change.

Let us assume that you changed the introduction a little. If you run the command

$ git status

you see that it tells you a file has been modified:

On branch master
Your branch is up-to-date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	modified:   chap_intro.tex

no changes added to commit (use "git add" and/or "git commit -a")

You can now add all the listed changes with

$ git add .

and finally commit the changes with

$ git commit -m "Made some changes in the introduction"

Sometimes it is useful to slowly keep adding changes, and commit once you have a natural block of changes that you would like to commit. (Say you are adding a proof of a theorem, you keep git add-ing your changes, and once you are done with the proof completely you can say git commit -m "Finished proof of blah theorem", which would be more meaningful than adding a commit message for every single sentence you add). Or if you really insist that you want to do both in one step, then you can use git commit -a -m "Commit message" but I generally prefer to add frequently and commit large sensible blocks of changes.

Now your local copy on your computer has the changes you just made. Whenever you are ready to push this to your fork on github.com, you can push the changes:

$ git push

It would probably ask you for your github username and password. You can now see the change added in your github home. It even tells you that your fork is ahead of the main repository by one commit.

** Note: ** If you do not like entering your username and password every time you make a push, you could either ask git to remember it for a small period of time using (https://help.github.com/articles/caching-your-github-password-in-git/). A better way (IMO) is using ssh instead of https to push (https://github.com/dasarpmar/lowerbounds-survey/wiki/Using-ssh-keys-to-push-changes)

Submitting your changes to me

Now suppose you think this is a good change and want me to update my repository to include this change, you can send me a 'pull request' (notice the link right next to the marked region in the screenshot above). You can also compare between your fork and mine using the 'compare' link to see what all has changed between them.

Click on the 'pull request' link and on 'Create pull request' on the resulting page. This give you a form where you can summarize the changes you made and you can submit the pull request.

Submitting a pull request

Once you submit your pull request, I will get a notification that you have made these changes on your fork. After reviewing your change, I can update my repository with these changes. If I have any other queries, I shall contact you for clarifications etc. Once I accept the pull request, you would get notified too.

Keeping your repository in sync

As you keep making changes to your local fork, other people might make changes to the main repository too. So it is important that you keep your local fork also updated with these other changes. Let us fix some notation. The copy of the folder on your computer will be called local copy. The fork of the main repository that you have on github.com will be called origin. The main repository will be called upstream. Normally, when you do a git clone from a repository, git automatically assigns that repository as origin. Let us first let your local copy know what upstream is.

$ git remote add upstream https://github.com/dasarpmar/lowerbounds-survey.git

Now git knows that this is your upstream mirror. You can check that using git remotes -v to list all the remote repositories that your local copy is aware of. To get all the changes from the upstream, run

$ git fetch upstream

This will put the upstream's master branch changes on new branches on your local copy such as upstream/master etc. You could take compare your master branch with the upstream's master branch via

$ git diff master upstream/master

If you want to add all changes on the upstream master branch to your master, you do that via the git merge command.

$ git merge upstream/master

If you haven't made any changes to your master during the time the upstream got updated, git would merge without any issues. However, if you have made changes in the meanwhile during which upstream also got updated, git may not know how to really merge these two changes. This is called a merge conflict and git will ask you to resolve it yourself.

Here is an example. Let us say that our contributor made a change to the readme to add a link to this wiki. Meanwhile, the upstream mirror also had a change to the readme (I changed it to give a link to the wiki too, but the sentence used there was different). Now our contributor ran a git merge on his local copy and this is what he got:

$ git merge upstream/master
Auto-merging README.md
CONFLICT (content): Merge conflict in README.md
Automatic merge failed; fix conflicts and then commit the result.

On opening README.md, the contributor sees that git has even marked the points where git is not sure of which change to keep.

...
<<<<<<< HEAD
Here is a link to the wiki: https://github.com/dasarpmar/lowerbounds-survey/wiki/Getting-started-with-github
=======
For people who are not familiar with using git or github, the wiki (https://github.com/dasarpmar/lowerbounds-survey/wiki/Getting-started-with-github) should be of some help. I shall also keep updating this to assist potential contributors.

>>>>>>> upstream/master
...

The contributor can now decide which change he wants to keep, and change the file accordingly. Once he is done, he can do a git commit as usual to finish his merge.

$ git add .
$ git commit -m "Made changes to README.md and resolved resulting conflict."

You can now push all your changes to origin too.

$ git push

Again, if this is different from upstream and you feel this is better, you can go ahead and issue another pull request to me.

Clone this wiki locally