Understanding GitHub

GitHub is a great improvement over subversion if for now other reason it has great performance for global teams that have network latency. It can be confusing when learning it though.To make things easier GitHub has created a GUI called GitHub for Windows, so you don't have to use the command line. The command line can do anything GitHub for Windows can. Here is one of the best tutorials I have found for using the GUI. It can still be a bit confusing because of the 2-3 repositories suggested by GitHub. Below is a diagram to show the steps needed to make a change, share it with others, and merge it back into the main repository.

Let's walk through the diagram in detail. The first thing to notice in this example is that there is an existing repository called AwesomeCode in github.com in the account for user Jane. The goal is that all changes will end up back in Jane's repository (repo). If your goal is not to contribute to the main repository and just want to work on your own copy (aka fork) that will not affect the main repo at all you don't create pull requests. The steps below assume you would like to contribute to the main repo (Jane's).

1. Fork - A fork is like a branch or a copy of the main repo. To fork a repo you need to use github.com and click the fork button. This will not do anything to your laptop. It will copy the main repo to your github.com account. Notice the difference in the urls for the main and your forked copy.

2. Clone - When you clone a repo you are getting a local copy of it on your laptop. You can use github.com to do this or you can use GitHub for Windows. When you do this you will need to specify the directory where the repo will be located. This command will create files in the specified directory, but it will also create a .git directory in that same directory you specified. This is known as the Local Repository or Index. The name index because there is and Index file in the .git directory.

3. Modify File - Here is where you use your favorite editor or program to modify or create a file.

4. Save - This is simply using your favorite editor or program to save the changes you made to the file to the local disk. If you re-open the file you will see the changes.

5. Commit - Commit in GitHub is different than in Subversion, CVS, etc because you don't have to be connected to the internet, cloud, network, etc to commit the change. All your commits will be done to your Local Repo. This make working with GibHub very efficient for networks with latency. Commits are not visible on the main or even your repo on github.com yet. If your laptop was lost so would your changes.

6. Push / Sync - Push is what the command is called, but in GitHub for Windows it is the Sync button. When you Push / Sync the changes on your Local Repo are pushed (similar to a commit) to your repository on github.com. You changes are now visible on your repository on github.com, but it is NOT visible in the main repository (Jane's). If you don't want to make your changes available to Jane then you are done. You have updated your repository.

7. Create Pull Request - A pull request is a way to say to share what you have done with others. You can use the pull request to get approval for your change, or get feedback, or help, etc. Other users can then comment on your pull request. It is the last step before merging your changes with the main repo. A pull request is a made while on your repository on github.com or you can now use GitHub for Windows to do it, but the pull request is actually available on the main repo (Jane's) under Pull Requests. Try to keep your pull requests small (5-10 lines or changes) and descriptive so other people can understand what your were doing.

8. Merge Pull Request - When you want to incorporate a the changes in a Pull Request into the main repo you need to merge the changes. Sometimes it can be automatically done, but other times it can't. Once the changes are merged the changes you made in your Pull Request are now part of the main repo. The general rule is that no Pull Requests should be merged into the main repo unless they are ready for releasing to production.