This site is from a past semester! The current version will be here when the new semester starts.

Git and Github

Init

Can create a local Git repo

Git Overview

Install SourceTree which is Git + a GUI for Git. If you prefer to use Git via the command line (i.e., without a GUI), you can install Git instead.

Suppose you want to create a repository in an empty directory things. Here are the steps:

Windows: Click FileClone/New…. Click on Create button.
Mac: New...Create New Repository.

Enter the location of the directory (Windows version shown below) and click Create.

Go to the things folder and observe how a hidden folder .git has been created.

Note: If you are on Windows, you might have to configure Windows Explorer to show hidden files.

SourceTree


Commit

Can commit using Git

Create an empty repo.

Create a file named fruits.txt in the working directory and add some dummy text to it.

Working directory: The directory the repo is based in is called the working directory.

Observe how the file is detected by Git.

The file is shown as ‘unstaged’

SourceTree

Although git has detected the file in the working directory, it will not do anything with the file unless you tell it to. Suppose we want to commit the current state of the file. First, we should stage the file.

Commit: Saving the current state of the working folder into the Git revision history.

Stage: Instructing Git to prepare a file for committing.

Select the fruits.txt and click on the Stage Selected button

fruits.txt should appear in the Staged files panel now.

SourceTree

Now, you can commit the staged version of fruits.txt

Click the Commit button, enter a commit message e.g. add fruits.txt in to the text box, and click Commit

SourceTree

Note the existence of something called the master branch. Git allows you to have multiple branches (i.e. it is a way to evolve the content in parallel) and Git creates a default branch named master on which the commits go on by default.

Do some changes to fruits.txt (e.g. add some text and delete some text). Stage the changes, and commit the changes using the same steps you followed before. You should end up with something like this.

Next, add two more files colors.txt and shapes.txt to the same working directory. Add a third commit to record the current state of the working directory.

Resources

  • Try Git is an online simulation/tutorial of Git basics. You can try its first few steps to solidify what you learned in this LO.


Ignore

Can set Git to ignore files

Add a file named temp.txt to the things repo you created. Suppose we don’t want this file to be revision controlled by Git. Let’s instruct Git to ignore temp.txt

The file should be currently listed under Unstaged files. Right-click it and choose Ignore…. Choose Ignore exact filename(s) and click OK.

Observe that a file named .gitignore has been created in the working directory root and has the following line in it.

temp.txt
SourceTree

The .gitignore file tells Git which files to ignore when tracking revision history. That file itself can be either revision controlled or ignored.

  • To version control it (the more common choice – which allows you to track how the .gitignore file changed over time), simply commit it as you would commit any other file.
  • To ignore it, follow the same steps we followed above when we set Git to ignore the temp.txt file.

Tag

Can tag commits using Git

Let's tag a commit in a local repo you have (e.g. the sampelrepo-things repo)

Right-click on the commit (in the graphical revision graph) you want to tag and choose Tag…

Specify the tag name e.g. v1.0 and click Add Tag.

The added tag will appear in the revision graph view.

SourceTree


Checkout

Can load a specific version of a Git repo

Git can show you what changed in each commit.

To see which files changed in a commit, click on the commit. To see what changed in a specific file in that commit, click on the file name.

SourceTree

Git can also show you the difference between two points in the history of the repo.

Select the two points you want to compare using Ctrl+Click.

The same method can be used to compare the current state of the working directory (which might have uncommitted changes) to a point in the history.

SourceTree

Git can load a specific version of the history to the working directory. Note that if you have uncommitted changes in the working directory, you need to stash them first to prevent them from being overwritten.

Double-click the commit you want to load to the working directory, or right-click on that commit and choose Checkout....

Click OK to the warning about ‘detached HEAD’ (similar to below).

The specified version is now loaded to the working folder, as indicated by the HEAD label. HEAD is a reference to the currently checked out commit.

If you checkout a commit that come before the commit in which you added the .gitignore file, Git will now show ignored fiels as ‘unstaged modifications’ because at that stage Git hasn’t been told to ignore those files.

To go back to the latest commit, double-click it.

SourceTree


Stash

Can use Git to stash files

You can use the git's stash feature to temporarily shelve (or stash) changes you've made to your working copy so that you can work on something else, and then come back and re-apply the stashed changes later on. -- adapted from this

Follow this article from SourceTree creators. Note the GUI shown in the article is slightly outdated but you should be able to map it to the current GUI.

Source Tree


Clone

Can clone a remote repo

Clone the sample repo samplerepo-things to your computer.

Note that the URL of the Github project is different form the URL you need to clone a repo in that Github project. e.g.

Github project URL: https://github.com/se-edu/samplerepo-things
Git repo URL: https://github.com/se-edu/samplerepo-things.git (note the .git at the end)

FileClone / New… and provide the URL of the repo and the destination directory.

SourceTree


Pull

Can pull changes from a repo

Clone the sample repo as explained in [Textbook Tools → Git & GitHub → Clone].

Delete the last two commits to simulate cloning the repo 2 commits ago.

Right-click the target commit (i.e. the commit that is 2 commits behind the tip) and choose Reset current branch to this commit.

Choose the Hard - … option and click OK.

This is what you will see.

Note the following (cross refer the screenshot above):

Arrow marked as a: The local repo is now at this commit, marked by the master label.
Arrow marked as b: origin/master label shows what is the latest commit in the master branch in the remote repo.

SourceTree

Now, your local repo state is exactly how it would be if you had cloned the repo 2 commits ago, as if somebody has added two more commits to the remote repo since you cloned it. To get those commits to your local repo (i.e. to sync your local repo with upstream repo) you can do a pull.

Click the Pull button in the main menu, choose origin and master in the next dialog, and click OK.

Now you should see something like this where master and origin/master are both pointing the same commit.

SourceTree


Push

Can push to a remote repo

  1. Create a GitHub account if you don't have one yet.

  2. Fork the samplerepo-things to your GitHub account:

    How to fork a repo?

  3. Clone the fork (not the original) to your computer.

  4. Create some commits in your repo.

  5. Push the new commits to your fork on GitHub

Click the Push button on the main menu, ensure the settings are as follows in the next dialog, and click the Push button on the dialog.

Tags are not included in a normal push. Remember to tick Push all tags when pushing to the remote repo if you want them to be pushed to the repo.

SourceTree


Branch

Can use Git branching

0. Observe that you are normally in the branch called master. For this, you can take any repo you have on your computer (e.g. a clone of the samplerepo-things).

SourceTree

1. Start a branch named feature1 and switch to the new branch.

Click on the Branch button on the main menu. In the next dialog, enter the branch name and click Create Branch

Note how the feature1 is indicated as the current branch.

SourceTree

2. Create some commits in the new branch. Just commit as per normal. Commits you add while on a certain branch will become part of that branch.

3. Switch to the master branch. Note how the changes you did in the feature1 branch are no longer in the working directory.

Double-click the master branch

SourceTree

4. Add a commit to the master branch. Let’s imagine it’s a bug fix.

5. Switch back to the feature1 branch (similar to step 3).

6. Merge the master branch to the feature1 branch, giving an end-result like the below. Also note how Git has created a merge commit.

Right-click on the master branch and choose merge master into the current branch. Click OK in the next dialog.

SourceTree

Observe how the changes you did in the master branch (i.e. the imaginary bug fix) is now available even when you are in the feature1 branch.

7. Add another commit to the feature1 branch.

8. Switch to the master branch and add one more commit.

9. Merge feature1 to the master branch, giving and end-result like this:

Right-click on the feature1 branch and choose Merge....

SourceTree

10. Create a new branch called add-countries, switch to it, and add some commits to it (similar to steps 1-2 above). You should have something like this now:

11. Go back to the master branch and merge the add-countries branch onto the master branch (similar to steps 8-9 above). While you might expect to see something like the below,

... you are likely to see something like this instead:

That is because Git does a fast forward merge if possible. Seeing that the master branch has not changed since you started the add-countries branch, Git has decided it is simpler to just put the commits of the add-countries branch in front of the master branch, without going into the trouble of creating an extra merge commit.

It is possible to force Git to create a merge commit even if fast forwarding is possible.

Tick the box shown below when you merge a branch:

SourceTree


Merge Conflicts

Can use Git to resolve merge conflicts

1. Start a branch named fix1 in a local repo. Create a commit that adds a line with some text to one of the files.

2. Switch back to master branch. Create a commit with a conflicting change i.e. it adds a line with some different text in the exact location the previous line was added.

3. Try to merge the fix1 branch onto the master branch. Git will pause mid-way during the merge and report a merge conflict. If you open the conflicted file, you will see something like this:

COLORS
------
blue
<<<<<<< HEAD
black
=======
green
>>>>>>> fix1
red
white

4. Observe how the conflicted part is marked between a line starting with <<<<<<< and a line starting with >>>>>>>, separated by another line starting with =======.

This is the conflicting part that is coming from the master branch:


<<<<<<< HEAD
black
=======

This is the conflicting part that is coming from the fix1 branch:


=======
green
>>>>>>> fix1

5. Resolve the conflict by editing the file. Let us assume you want to keep both lines in the merged version. You can modify the file to be like this:

COLORS
------
blue
black
green
red
white

6. Stage the changes, and commit.


Create PRs

Can create PRs on GitHub

1. Fork the samplerepo-pr-practice onto your GitHub account. Clone it onto your computer.

2. Create a branch named add-intro in your clone. Add a couple of commits which adds/modifies an Introduction section to the README.md. Example:


# Introduction
Creating Pull Requsts (PRs) is needed when using RCS in a multi-person projects.
This repo can be used to practice creating PRs.

3. Push the add-intro branch to your fork.

SourceTree

4. Create a Pull Request from the add-intro branch in your fork to the master branch of the same fork (i.e. your-user-name/samplerepo-pr-practice, not se-edu/samplerepo-pr-practice), as described below.

4a. Go to the GitHub page of your fork (i.e. https://github.com/{your_username}/samplerepo-pr-practice), click on the Pull Requests tab, and then click on New Pull Request button.

4b. Select base fork and head fork as follows:

  • base fork: your own fork (i.e. {your user name}/samplerepo-pr-practice, NOT se-edu/samplerepo-pr-practice)
  • head fork: your own fork.

The base fork is where changes should be applied. The head fork contains the changes you would like to be applied.

4c. (1) Set the base branch to master and head branch to add-intro, (2) confirm the diff contains the changes you propose to merge in this PR (i.e. confirm that you did not accidentally include extra commits in the branch), and (3) click the Create pull request button.

4d. (1) Set PR name, (2) set PR description, and (3) Click the Create pull request button.

A common newbie mistake when creating branch-based PRs is to mix commits of one PR with another. To learn how to avoid that mistake, you are encouraged to continue and create another PR as explained below.

5. In your local repo, create a new branch add-summary off the master branch.

When creating the new branch, it is very important that you switch back to the master branch first. If not, the new branch will be created off the current branch add-intro. And that is how you end up having commits of the first PR in the second PR as well.

6. Add a commit in the add-summary branch that adds a Summary section to the README.md, in exactly the same place you added the Introduction section earlier.

7. Push the add-summary to your fork and create a new PR similar to before.


Manage PRs

Can review and merge PRs on GitHub

1. Go to the GitHub page of your fork and review the add-intro PR you created previously in [Tools → Git & GitHub → Create PRs] to simulate the PR being reviewed by another developer, as explained below. Note that some features available to PR reviewers will be unavailable to you because you are also the author of the PR.

1a. Go to the respective PR page and click on the Files changed tab. Hover over the line you want to comment on and click on the icon that appears on the left margin. That should create a text box for you to enter your comment.

1b. Enter some dummy comment and click on Start a review button.

1c. Add a few more comments in other places of the code.

1d. Click on the Review Changes button, enter an overall comment, and click on the Submit review button.

2. Update the PR to simulate revising the code based on reviewer comments. Add some more commits to the add-intro branch and push the new commits to the fork. Observe how the PR is updated automatically to reflect the new code.

3. Merge the PR. Go to the GitHub page of the respective PR, scroll to the bottom of the Conversation tab, and click on the Merge pull request button, followed by the Confirm merge button. You should see a Pull request successfully merged and closed message after the PR is merged.

4. Sync the local repo with the remote repo. Because of the merge you did on the GitHub, the master branch of your fork is now ahead of your local repo by one commit. To sync the local repo with the remote repo, pull the master branch to the local repo.

git checkout master
git pull origin master

Observe how the add-intro branch is now merged to the master branch in your local repo as well.

5. De-conflict the add-summary PR that you created earlier. Note that GitHub page for the add-summary PR is now showing a conflict (when you scroll to the bottom of that page, you should see a message This branch has conflicts that must be resolved). You can resolve it locally and update the PR accordingly, as explained below.

5a. Switch to the add-summary branch. To make that branch up-to-date with the master branch, merge the master branch to it, which will surface the merge conflict. Resolve it and complete the merge.

5b. Push the updated add-summary branch to the fork. That will remove the 'merge conflicts' warning in the GitHub page of the PR.

6. Merge the add-summary PR using the GitHub interface, similar to how you merged the previous PR.

Note that you could have merged the add-summary branch to the master branch locally before pushing it to GitHub. In that case, the PR will be merged on GitHub automatically to reflect that the branch has been merged already.


Forking Workflow

Can follow Forking Workflow

This activity is best done as a team. If you are learning this alone, you can simulate a team by using two different browsers to log into GitHub using two different accounts.

  1. One member: set up the team org and the team repo.

  2. Each team member: create PRs via own fork

    • Fork that repo from your team org to your own GitHub account.
    • Create a PR to add a file yourName.md (e.g. jonhDoe.md containing a brief resume of yourself (branch → commit → push → create PR)
  3. For each PR: review, update, and merge.

    • A team member (not the PR author): Review the PR by adding comments (can be just dummy comments).
    • PR author: Update the PR by pushing more commits to it, to simulate updating the PR based on review comments.
    • Another team member: Merge the PR using the GitHub interface.
    • All members: Sync your local repo (and your fork) with upstream repo. In this case, your upstream repo is the repo in your team org.
  4. Create conflicting PRs.

    • Each team member: Create a PR to add yourself under the Team Members section in the README.md.
    • One member: in the master branch, remove John Doe and Jane Doe from the README.md, commit, and push to the main repo.
  5. Merge conflicting PRs one at a time. Before merging a PR, you’ll have to resolve conflicts. Steps:

    • [Optional] A member can inform the PR author (by posting a comment) that there is a conflict in the PR.
    • PR author: Pull the master branch from the repo in your team org. Merge the pulled master branch to your PR branch. Resolve the merge conflict that crops up during the merge. Push the updated PR branch to your fork.
    • Another member or the PR author: When GitHub does not indicate a conflict anymore, you can go ahead and merge the PR.