Github-tutorial

From Grundy

GitHub is a code hosting platform for version control and collaboration. It lets you and others work together on projects from anywhere. This tutorial teaches you GitHub essentials like repositories, branches, commits, and Pull Requests. You’ll create your own Hello World repository and learn GitHub’s Pull Request workflow, a popular way to create and review code.

If you are looking for the offline source code versioning system, it can be found here.

Getting started with GitHub

A REPOSITORY

A repository is usually used to organize a single project. Repositories can contain folders and files, images, videos, spreadsheets, and data sets – anything your project needs. We recommend including a README, or a file with information about your project. GitHub makes it easy to add one at the same time you create your new repository. 
To create a new repository
1. In the upper right corner, next to your avatar or identicon, click  and then select New repository.
2. Name your repository.
3. Write a short description.
4. Select Initialize this repository with a README.

Click Create repository

Adding Collaborators
You can add your team members as collaborators, so you guys can work at the same repository simultaneously.
for adding a collaborator, simply go to the repository, click on settings, and then on the collaborators tab on the left.


Clone

Cloning as the name suggests is the process of making an exact copy. git clone command takes as input a reference repository and make a copy in a new directory, at another location which is usually in your PC.

git clone <repository>

Through this command the target repository is copied with same name. If you want you could clone it with a different name too.

git clone <repository> <directory>

Note that cloning of local repository is also possible. But that is inevitably the same as copying (in the literal sense) the repository from one place to other.

  • On cloning a repository, the remote origin is by default set to the referenced repository (the repository which you cloned)

You can see this by running the command git remote -v

origin	https://github.com/username/repository (fetch)
origin	https://github.com/username/repository (push)

Fork

Fork refers to making a copy of someone else's repository to your github account. Though clone and fork seem similar in definition, there's a fundamental difference, the copy made through fork remains on your github account. No local copies are made. Whereas in case of cloning a local version of the referenced repository is made without any changes to your github account. I hope the above explanation makes it clear.

  • Forking a repository allows you to freely experiment with changes without affecting the original project.
  • Most commonly, forks are used to either propose changes to someone else's project or to use someone else's project as a starting point for your own idea.

Clone vs Fork What should I do?

  • Ideally if you want to contribute to any open-source project you have to first fork the repository and then clone it. Note the order above. This way the local copy you have will have two remotes by default origin and upstream
  • The upstream points to the original remote repository whereas origin points to the forked repository in your github account.

Remote

Remotes on broader sense are just connecting links between repositories. You can view them as pointers to location where the other repository is present. Remote repository on the other hand is usually used to refer to the repository you have on your github account. (Just a way of saying) You can have several of them, each of which generally is either read-only or read/write for you. The command lists the short names of all the remotes you have

git remote

You can use the flag -v which will list the remotes with their referenced URL's and actions (push and fetch)

git remote -v

Other Commands
Adding a remote

git remote add <name> <url>

Renaming a remote

git remote rename <old> <new>

Deleting a remote

git remote remove <name>


Fetch

When you fetch, Git gathers any commits from the target branch that do not exist in your current branch and stores them in your local repository. However, it does not merge them with your current branch. This is particularly useful if you need to keep your repository up to date, but are working on something that might break if you update your files. To integrate the commits into your master branch, you use merge. The command you use for fetching is

git fetch <remote>

For ex, we can use

git fetch upstream

if u want to fetch only a particular branch, u can use

git fetch <remote> <branch>


Pull

When you use pull, Git tries to automatically do your work for you. It is context sensitive, so Git will merge any pulled commits into the branch you are currently working in. pull automatically merges the commits without letting you review them first. the command for pulling is :

git pull <remote>

Git pull is essentially git fetch + git merge, ie., It fetches the changes and merge them automatically.

Push

pushing sends the recent commit history from your local repository up to GitHub. If you’re the only one working on a repository, pushing is fairly simple. If there are others accessing the repository, you may need to pull before you can push.

git push <remote> <branch>

therefore whenever you are working on a project along with your team-mates, you must always pull the remote repository first, then create a branch and make changes, and finally push the changes. this way you can avoid possible merge-conflicts( this part is explained later).

Branches

Branching as the name suggests is the process of deviating away from the main path. In git, branches are made to work on certain features or issues without disturbing the master branch and then merging back when the feature/issue is fully added/resolved.

In order to create a new branch use

git branch <name_of_branch>

This creates a copy of the current branch you are on with the name <name_of_branch>

If you just type git branch it will list all the branch of the repository and highlight the branch you are currently on.

Deleting a Branch

git branch -d <branch_name>

Note that this will show error if the branch is not fully merged with master Use -D flag if you want to force delete a branch. -D = -d --force

Renaming a Branch

git branch -m <oldname> <newname>

Merge and Merge Conflicts

Remember that we just talked about branches, the major purpose of branching was to work on the project feature or bug separately until you are sure that your changes are ready to be deployed to master branch. Now that you have done that you want your changes to be merged with the main branch. Git is a smart tool when it comes to merging, it will automatically try to accommodate all the changes you have done to the file and most of the time you'll see a merge successful message.

The tricky part is that when multiple users are working on same project, chances are that they would modify the same file or same part of project simultaneously working separately in their own branches. Now suppose that one user has committed his changes, then when the second user tries to push his changes he gets merge conflict message. (This is because git is unable to decide which of these changes should be accommodated)

Now its your responsibility to manually resolve this conflict by deciding what to do with this part of the file. You can keep either of them, both of them or even none of them. Once you're done modifying the file you need to commit this change. The merge is complete now.

Pull Requests

Let's say that you made changes to some files in a repository that you forked + cloned. Now you want these to reflect in the upstream remote too. What you would generally try to do is to push the changes to the upstream remote

git push upstream master

If you would actually try the above command you'll see that it doesn't work and shows an error that you don't have push rights to the repository. This is what was expected because anyone shouldn't be allowed to push directly into the codebase without any verification, testing because that commit will further mess up everybody's local repository once they pull/fetch.

Any project in github has level of access/rights given to collaborators, just like an organisation. The owner holds the complete right (deleting a repository, pushing directly etc). Other people can watch the repository and propose changes but not merge them on their own. They need permission from the owner.

What should I do then ?

Send a pull request to the upstream repository. As name suggests, pull requests are basically the request you send to the owner/collaborators of repository to consider your changes and merge them into their branch. Now often these changes must pass some tests or must be reviewed by multiple person before they are merged into the main codebase. It is often the case that the pull requests are rejected ("closed") because they fail some tests or that the style does not match that of the organisations. In either case there will be people telling you what changes you need to make etc if the organisation is welcoming.

Say for example you're doing a project with your friends and you created a repository. Now every time your friends make changes they'll have to wait for your permission to merge these changes which is not what you want. You can give them collaborator right's using which they'll be able to push directly to any branch without your permission.

You can also create a pull request within repository, from one branch (say feature) to the other (say master). You'll have to merge it yourself though. As such there might not seem a very good reason to send pull request within repositories but they come handy when you are working on multiple features at the same time.

Difference between GitHub, GitLab, BitBucket

If you want to just contribute to other open-source projects then use GitHub. These days GitHub acts as online portfolio for a person, where one can upload some of his own projects and mention the GitHub account in his resume. Having an active GitHub account helps to distinguish one from others, and shows how much he has worked for open source. It also provides free private repositories with unlimited collaborators.

GitLab is a decent solution, especially for Digital Ocean and GitLab is free for private repositories. Many organizations use GitLab while they want their codebase to be private. Bitbucket restricts you to work with only 5 people for free, GitLab.com is completely free. So if you want to work with Digital Ocean then GitLab is best and when you want to host your 1000 repositories and 100 colleagues somewhere then GitLab.com is the solution.

Bitbucket is one of the most popular while it comes at an organization’s point of view. More organizations host their projects in Bitbucket compared to GitLab, due to its user-friendly interface. Bitbucket Cloud has Mercurial support. Bitbucket also offers free private repositories so only members can access the codebase.

See Also

Gitub Hello World