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

Git Learning Trail

This learning trail is for those who are new to Git and would like to learn it in advance to prepare for the course.
These topics are covered during the regular course schedule and in the course textbook as well. So, doing this in advance is optional, but doing so can reduce your workload during the regular semester.

Note before you start:

  • Watching the given videos is optional but recommended. They cover almost the same ground as the text content, but provide a more visual view of the explanations. Watch if you can spare the time.
  • Doing the given activities is strongly recommended. It is not enough to just go through the content -- you need to get some hands-on practice.
  • If you encounter any problems while following this learning trial, you can post in the course forum (requires a Github account).

Intro to RCS

Git is a tool used for revision control. So, let's start by learning some basic revision control concepts.

RCS: Revision Control

[Textbook location: Project Management → Revision Control → What]

Can explain revision control

Revision control is the process of managing multiple versions of a piece of information. In its simplest form, this is something that many people do by hand: every time you modify a file, save it under a new name that contains a number, each one higher than the number of the preceding version.

Manually managing multiple versions of even a single file is an error-prone task, though, so software tools to help automate this process have long been available. The earliest automated revision control tools were intended to help a single user to manage revisions of a single file. Over the past few decades, the scope of revision control tools has expanded greatly; they now manage multiple files, and help multiple people to work together. The best modern revision control tools have no problem coping with thousands of people working together on projects that consist of hundreds of thousands of files.

Revision control software will track the history and evolution of your project, so you don't have to. For every change, you'll have a log of who made it; why they made it; when they made it; and what the change was.

Revision control software makes it easier for you to collaborate when you're working with other people. For example, when people more or less simultaneously make potentially incompatible changes, the software will help you to identify and resolve those conflicts.

It can help you to recover from mistakes. If you make a change that later turns out to be an error, you can revert to an earlier version of one or more files. In fact, a really good revision control tool will even help you to efficiently figure out exactly when a problem was introduced.

It will help you to work simultaneously on, and manage the drift between, multiple versions of your project. Most of these reasons are equally valid, at least in theory, whether you're working on a project by yourself, or with a hundred other people.

-- [adapted from bryan-mercurial-guide]



Revision: A revision (some seem to use it interchangeably with version while others seem to distinguish the two -- here, let us treat them as the same, for simplicity) is a state of a piece of information at a specific time that is a result of some changes to it e.g., if you modify the code and save the file, you have a new revision (or a new version) of that file.

RCS: Revision control software are the software tools that automate the process of Revision Control i.e. managing revisions of software artifacts.

Revision control software are also known as Version Control Software (VCS), and by a few other names.

Git is the most widely used RCS today. Other RCS tools include Mercurial, Subversion (SVN), Perforce, CVS (Concurrent Versions System), Bazaar, TFS (Team Foundation Server), and Clearcase.

Github is a web-based project hosting platform for projects using Git for revision control. Other similar services include GitLab, BitBucket, and SourceForge.


RCS: Repositories

[Textbook location: Project Management → Revision Control → Repositories]

Can explain repositories

The repository is the database that stores the revision history. Suppose you want to apply revision control on files in a directory called ProjectFoo. In that case, you need to set up a repo (short for repository) in the ProjectFoo directory, which is referred to as the working directory of the repo. For example, Git uses a hidden folder named .git inside the working directory, to store the database of the working directory's revision history.

Repository (repo for short): The database of the history of a directory being tracked by an RCS software (e.g. Git).

Working directory: the root directory revision-controlled by Git (e.g., the directory in which the repo was initialized).

You can have multiple repos in your computer, each repo revision-controlling files of a different working directory, for examples, files of different projects.




Phase 1: Recording Revision History

In this phase, you'll start using Git to practice recording revision histories in your own computer.

Admin Lectures → Extract

Tips for watching lecture videos
  • You are recommended to watch Videos provided at faster speeds (x1.25 or even x1.5) to save time.
  • You'll need to use your NUSNET login to access them.

Git:init

[Textbook location: Tools → Git and GitHub → init: Getting started]

Video

Can create a local Git repo

Let's take your first few steps in your Git journey.

0. Take a peek at the full picture(?). Optionally, if you are the sort who prefers to have some sense of the full picture before you get into the nitty-gritty details, watch the video in the panel below:

Git Overview


1. First, install Sourcetree (installation instructions), 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.

2. Next, create a directory for the repo (e.g., a directory named things).

3. Then, initialize a repository in that directory.

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.

Windows: you might have to configure Windows Explorer to show hidden files.


Open a Git Bash Terminal.

If you installed Sourcetree, you can click the Terminal button to open a GitBash terminal (on a Linux/Mac environment, even a regular terminal should do).

Navigate to the things directory.
Use the command git init which should initialize the repo.

$ cd /c/repos/things
$ git init

Initialized empty Git repository in c:/repos/things/.git/

You can use the list all command ls -a to view all files, which should show the .git directory that was created by the previous command.

$ ls -a
.  ..  .git

You can also use the git status command to check the status of the newly-created repo. It should respond with something like the following:

$ git status

# On branch master
#
# No commits yet
#
nothing to commit (create/copy files and use "git add" to track)

As you see above, this textbook explains how to use Git via Sourcetree (a GUI client) as well as via the Git CLI. If you are new to Git, we recommend you learn both the GUI method and the CLI method -- The GUI method will help you visualize the result better while the CLI method is more universal (i.e., you will not be tied to any GUI) and more flexible/powerful.

It is fine to learn the CLI way only (using Sourcetree is optional), especially if you normally prefer to work with CLI user GUI.

If you are new to Git, we caution you against using Git or GitHub features that come with the IDE as it is better to learn Git independent of any other tool. Similarly, using clients provided by GitHub (e.g., GitHub Desktop GUI client) will make it harder for you to separate Git features from GitHub features.


RCS: Saving History

[Textbook location: Project Management → Revision Control → Saving history]

Can explain saving history

Tracking and ignoring

In a repo, you can specify which files to track and which files to ignore. Some files such as temporary log files created during the build/test process should not be revision-controlled.

Staging and committing

Committing saves a snapshot of the current state of the tracked files in the revision control history. Such a snapshot is also called a commit (i.e. the noun).

Commit (noun): a change (aka a revision) saved in the Git revision history.
(verb): the act of creating a commit i.e., saving a change in the working directory into the Git revision history.

When ready to commit, you first add the specific changes you want to commit to a staging area. This intermediate step allows you to commit only some changes while saving other changes for a later commit.

Stage (verb): Instructing Git to prepare a file for committing.




Git: commit

[Textbook location: Tools → Git and GitHub → commit: Saving changes to history]

Video

Can commit using Git

After initializing a repository, Git can help you with revision controlling files inside the working directory. However, it is not automatic. You need to tell Git which of your changes (aka revisions) should be committed to its memory for later use. Saving changes into Git's memory in that way is called committing and a change saved to the revision history is called a commit.

Here are the steps you can follow to learn how to create Git commits:

1. Do some changes to the content inside the working directory e.g., create a file named fruits.txt in the things directory and add some dummy text to it.

2. Observe how the file is detected by Git.

The file is shown as ‘unstaged’.


You can use the git status command to check the status of the working directory.

$ git status

# On branch master
#
# No commits yet
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#   a.txt
nothing added to commit but untracked files present (use "git add" to track)

3. Stage the changes to commit: Although Git has detected the file in the working directory, it will not do anything with the file unless you tell it to. Suppose you want to commit the current changes to the file. First, you should stage the file, which is how you tell Git which changes you want to include in the next commit.

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

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

If Sourcetree shows a \ No newline at the end of the file message below the staged lines (i.e., below the cherries line in the above screenshot), that is because you did not hit enter after entering the last line of the file (hence, Git is not sure if that line is complete). To rectify, move the cursor to end of the last line in that file and hit enter (like you are adding a blank line below it). This new change will now appear as an 'unstaged' change. Stage it as well.


You can use the stage or the add command (they are synonyms, add is the more popular choice) to stage files.

$ git add fruits.txt
$ git status

# On branch master
#
# No commits yet
#
# Changes to be committed:
#   (use "git rm --cached <file>..." to unstage)
#
#       new file:   fruits.txt
#

4. Commit the staged version of fruits.txt.

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


Use the commit command to commit. The -m switch is used to specify the commit message.

$ git commit -m "Add fruits.txt"

You can use the log command to see the commit history.

$ git log

commit 8fd30a6910efb28bb258cd01be93e481caeab846
Author: … < … @... >
Date:   Wed Jul 5 16:06:28 2017 +0800

  Add fruits.txt

Note the existence of something called the master branch. Git uses a mechanism called branches to facilitate evolving file content in parallel (we'll learn git branching in a later topic). Furthermore, Git auto-creates a branch named master on which the commits go on by default.

Expand the BRANCHES menu and click on the master to view the history graph, which contains only one node at the moment, representing the commit you just added. Also note a label master attached to the commit.

This label points to the latest commit on the master branch.


Run the git status command and note how the output contains the phrase on branch master.


5. Do a few more commits.

  1. Make 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.

  2. 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.

    You can decide what to stage and what to leave unstaged. When staging changes to commit, you can leave some files unstaged, if you wish to not include them in the next commit. In fact, Git even allows some changes in a file to be staged, while others changes in the same file to be unstaged. This flexibility is particularly useful when you want to put all related changes into a commit while leaving out unrelated changes.

6. See the revision graph: Note how commits form a path-like structure aka the revision tree/graph. In the revision graph, each commit is shown as linked to its 'parent' commit (i.e., the commit before it).

To see the revision graph, click on the History item (listed under the WORKSPACE section) on the menu on the right edge of Sourcetree.


The gitk command opens a rudimentary graphical view of the revision graph.


How do undo/delete a commit?

To undo the last commit, right-click on the commit just before it, and choose Reset current branch to this commit.

In the next dialog, choose the mode Mixed - keep working copy but reset index option. This will make the offending commit disappear but will keep the changes that you included in that commit intact.

If you use the Soft - ... mode instead, the last commit will be undone as before, but the changes included in that commit will stay in the staging area.

To delete the last commit entirely (i.e., undo the commit and also discard the changes included in that commit), do as above but choose the Hard - ... mode instead.

To undo/delete last n commits, right-click on the commit just before the last n commits, and do as above.


To undo the last commit, but keep the changes in the staging area, use the following command.

$ git reset --soft HEAD~1

To undo the last commit, and remove the changes from the staging area (but not discard the changes), used --mixed instead of --soft.

$ git reset --mixed HEAD~1

To delete the last commit entirely (i.e., undo the commit and also discard the changes included in that commit), do as above but use the --hard flag instead (i.e., do a hard reset).

$ git reset --hard HEAD~1

To undo/delete last n commits: HEAD~1 is used to tell get you are targeting the commit one position before the latest commit -- in this case the target commit is the one we want to reset to, not the one we want to undo (as the command used is reset). To undo/delete two last commits, you can use HEAD~2, and so on.



Git: .ignore

[Textbook location: Tools → Git and GitHub → Omitting files from revision control]

Video

Can set Git to ignore files

Often, there are files inside the Git working folder that you don't want to revision-control e.g., temporary log files. Follow the steps below to learn how to configure Git to ignore such files.

1. Add a file into your repo's working folder that you supposedly don't want to revision-control e.g., a file named temp.txt. Observe how Git has detected the new file.

2. Configure Git to ignore that file:

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.

.gitignore
temp.txt

Create a file named .gitignore in the working directory root and add the following line in it.

.gitignore
temp.txt

The .gitignore file

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 changes over time), simply commit it as you would commit any other file.

  • To ignore it, follow the same steps you followed above when you set Git to ignore the temp.txt file.

  • It supports file patterns e.g., adding temp/*.tmp to the .gitignore file prevents Git from tracking any .tmp files in the temp directory.

More information about the .gitignore file: git-scm.com/docs/gitignore

Files recommended to be omitted from version control

  • Binary files generated when building your project e.g., *.class, *.jar, *.exe (reasons: 1. no need to version control these files as they can be generated again from the source code 2. Revision control systems are optimized for tracking text-based files, not binary files.
  • Temporary files e.g., log files generated while testing the product
  • Local files i.e., files specific to your own computer e.g., local settings of your IDE
  • Sensitive content i.e., files containing sensitive/personal information e.g., credential files, personal identification data (especially, if there is a possibility of those files getting leaked via the revision control system).

Phase 2: Using Revision History

In this phase, you'll learn how to make use of the revision history contained inside a Git repository.

RCS: Using History

[Textbook location: Project Management → Revision Control → Using history]

Can explain basic concepts of how RCS history is used

RCS tools store the history of the working directory as a series of commits. This means you should commit after each change that you want the RCS to 'remember'.

Each commit in a repo is a recorded point in the history of the project that is uniquely identified by an auto-generated hash e.g. a16043703f28e5b3dab95915f5c5e5bf4fdc5fc1.

You can tag a specific commit with a more easily identifiable name e.g. v1.0.2.

To see what changed between two points of the history, you can ask the RCS tool to diff the two commits in concern.

To restore the state of the working directory at a point in the past, you can checkout the commit in concern. i.e., you can traverse the history of the working directory simply by checking out the commits you are interested in.


Git: tag

[Textbook location: Tools → Git and GitHub → tag: Naming commits]

Video

Can tag commits using Git

Each Git commit is uniquely identified by a hash e.g., d670460b4b4aece5915caf5c68d12f560a9fe3e4. As you can imagine, using such an identifier is not very convenient for our day-to-day use. As a solution, Git allows adding a more human-readable tag to a commit e.g., v1.0-beta.

Here's how you can tag a commit in a local 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.


To add a tag to the current commit as v1.0:

$ git tag –a v1.0

To view tags:

$ git tag

To learn how to add a tag to a past commit, go to the ‘Git Basics – Tagging’ page of the git-scm book and refer the ‘Tagging Later’ section.


After adding a tag to a commit, you can use the tag to refer to that commit, as an alternative to using the hash.

Tags are different from commit messages, in purpose and in form. A commit message is a description of the commit that is part of the commit itself. A tags is a short name for a commit, which exists as a separate entity that points to a commit.


Git: diff

[Textbook location: Tools → Git and GitHub → diff: Comparing revisions]

Video

Can compare git revisions

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.


$ git show < part-of-commit-hash >

Example:

$ git show 5bc0e306

commit 5bc0e30635a754908dbdd3d2d833756cc4b52ef3
Author: … < … >
Date:   Sat Jul 8 16:50:27 2017 +0800

    fruits.txt: replace banana with berries

diff --git a/fruits.txt b/fruits.txt
index 15b57f7..17f4528 100644
--- a/fruits.txt
+++ b/fruits.txt
@@ -1,3 +1,3 @@
 apples
-bananas
+berries
 cherries

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 differences between the two selected versions will show up in the bottom half of Sourcetree, as shown in the screenshot below.

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.


The diff command can be used to view the differences between two points of the history.

  • git diff: shows the changes (uncommitted) since the last commit.
  • git diff 0023cdd..fcd6199: shows the changes between the points indicated by commit hashes.
    Note that when using a commit hash in a Git command, you can use only the first few characters (e.g., first 7-10 chars) as that's usually enough for Git to locate the commit.
  • git diff v1.0..HEAD: shows changes that happened from the commit tagged as v1.0 to the most recent commit.


Git: checkout

[Textbook location: Tools → Git and GitHub → checkout: Retrieving a specific revision]

Video

Can load a specific version of a Git repo

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 comes before the commit in which you added the .gitignore file, Git will now show ignored files 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.


Use the checkout <commit-identifier> command to change the working directory to the state it was in at a specific past commit.

  • git checkout v1.0: loads the state as at commit tagged v1.0
  • git checkout 0023cdd: loads the state as at commit with the hash 0023cdd
  • git checkout HEAD~2: loads the state that is 2 commits behind the most recent commit

For now, you can ignore the warning about ‘detached HEAD’.



Git: stash

[Textbook location: Tools → Git and GitHub → stash: Shelving changes temporarily]

Video

Can use Git to stash files

You can use 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 Atlassian

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



Phase 3: Working With Remote Repos

In this phase, you'll start interacting with git repositories hosted on remote servers.

RCS: Remote Repositories

[Textbook location: Project Management → Revision Control → Remote repositories]

Video

Can explain remote repositories

Remote repositories are repos that are hosted on remote computers and allow remote access. They are especially useful for sharing the revision history of a codebase among team members of a multi-person project. They can also serve as a remote backup of your codebase.

It is possible to set up your own remote repo on a server, but the easier option is to use a remote repo hosting service such as GitHub or BitBucket.

You can clone a repo to create a copy of that repo in another location on your computer. The copy will even have the revision history of the original repo i.e., identical to the original repo. For example, you can clone a remote repo onto your computer to create a local copy of the remote repo.

When you clone from a repo, the original repo is commonly referred to as the upstream repo. A repo can have multiple upstream repos. For example, let's say a repo repo1 was cloned as repo2 which was then cloned as repo3. In this case, repo1 and repo2 are upstream repos of repo3.

You can pull from one repo to another, to receive new commits in the second repo, but only if the repos have a shared history. Let's say some new commits were added to the after you cloned it and you would like to copy over those new commits to your own clone i.e., sync your clone with the upstream repo. In that case, you pull from the upstream repo to your clone.

You can push new commits in one repo to another repo which will copy the new commits onto the destination repo. Note that pushing to a repo requires you to have write-access to it. Furthermore, you can push between repos only if those repos have a shared history among them (i.e., one was created by copying the other at some point in the past).

Cloning, pushing, and pulling can be done between two local repos too, although it is more common for them to involve a remote repo.

A repo can work with any number of other repositories as long as they have a shared history e.g., repo1 can pull from (or push to) repo2 and repo3 if they have a shared history between them.

A fork is a remote copy of a remote repo. As you know, cloning creates a local copy of a repo. In contrast, forking creates a remote copy of a Git repo hosted on GitHub. This is particularly useful if you want to play around with a GitHub repo but you don't have write permissions to it; you can simply fork the repo and do whatever you want with the fork as you are the owner of the fork.

A pull request (PR for short) is a mechanism for contributing code to a remote repo, i.e., "I'm requesting you to pull my proposed changes to your repo". For this to work, the two repos must have a shared history. The most common case is sending PRs from a fork to its repo.

Here is a scenario that includes all the concepts introduced above (click inside the slide to advance the animation):


Git: clone

[Textbook location: Tools → Git and GitHub → clone: Copying a repo]

Video

Can clone a remote repo

Given below is an example scenario you can try yourself to learn Git cloning.

Suppose you want to clone the sample repo samplerepo-things to your computer.

Note that the URL of the GitHub project is different from 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.


You can use the clone command to clone a repo.

Follow the instructions given here.



Git: pull

[Textbook location: Tools → Git and GitHub → pull, fetch: Downloading data from other repos]

Video

Can pull changes from a repo

Here's a scenario you can try in order to learn how to pull commits from another repo to yours.

1. Clone a repo (e.g., the repo used in [Git & GitHub → Clone]) to be used for this activity.

2. Delete the last few commits to simulate cloning the repo a few 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: The origin/master label shows what is the latest commit in the master branch in the remote repo. origin is the default name given to the upstream repo you cloned from.


Use the reset command to delete commits at the tip of the revision history.

$ git reset --hard HEAD~2

More info on the git reset command can be found here.


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.

3. Pull from the other repo: To get those missing 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.


$ git pull origin

You can also do a fetch instead of a pull in which case the new commits will be downloaded to your repo but the working directory will remain at the current commit. To move the current state to the latest commit that was downloaded, you need to do a merge. A pull is a shortcut that does both those steps in one go.

Working with multiple remotes

When you clone a repo, Git automatically adds a remote repo named origin to your repo configuration. As you know, you can pull commits from that repo. As you know, a Git repo can work with remote repos other than the one it was cloned from.

To communicate with another remote repo, you can first add it as a remote of your repo. Here is an example scenario you can follow to learn how to pull from another repo:

  1. Open the local repo in Sourcetree. Suggested: Use your local clone of the samplerepo-things repo.

  2. Choose RepositoryRepository Settings menu option.

  3. Add a new remote to the repo with the following values.

    • Remote name: the name you want to assign to the remote repo e.g., upstream1
    • URL/path: the URL of your repo (ending in .git) that. Suggested: https://github.com/se-edu/samplerepo-things-2.git (samplerepo-things-2 is another repo that has a shared history with samplerepo-things)
    • Username: your GitHub username

  4. Now, you can fetch or pull (pulling will fetch the branch and merge the new code to the current branch) from the added repo as you did before but choose the remote name of the repo you want to pull from (instead of origin):
    Click the Fetch button or the Pull button first.

    If the Remote branch to pull dropdown is empty, click the Refresh button on its right.

  5. If the pull from the samplerepo-things-2 was successful, you should have received one more commit into your local repo.


  1. Navigate to the folder containing the local repo.

  2. Set the new remote repo as a remote of the local repo.
    command: git remote add {remote_name} {remote_repo_url}
    e.g., git remote add upstream1 https://github.com/johndoe/foobar.git

  3. Now you can fetch or pull (pulling will fetch the branch and merge the new code to the current branch) from the new remote.
    e.g., git fetch upstream1 master followed by git merge upstream1/master, or,
    git pull upstream1 master



Github: fork

[Textbook location: Tools → Git and GitHub → Fork: Creating a remote copy]

Video

Can fork a repo

Given below is a scenario you can try in order to learn how to fork a repo:.

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

1. Go to the GitHub repo you want to fork e.g., samplerepo-things

2. Click on the button on the top-right corner. In the next step,

  • choose to fork to your own account or to another GitHub organization that you are an admin of.
  • Un-tick the [ ] Copy the master branch only option, so that you get copies of other branches (if any) in the repo.

As you might have guessed from the above, forking is not a Git feature, but a feature provided by remote Git hosting services such as Github.

GitHub does not allow you to fork the same repo more than once to the same destination. If you want to re-fork, you need to delete the previous fork.


Git: push

[Textbook location: Tools → Git and GitHub → push: Uploading data to other repos]

Video

Can push to a remote repo

Given below is a scenario you can try in order to learn how to push commits to a remote repo hosted on GitHub:

1. Fork an existing GitHub repo (e.g., samplerepo-things) to your GitHub account.

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

3. Commit some changes in your local repo.

4. 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.


Use the command git push origin master. Enter your Github username and password when prompted.


5. Add a few more commits, and tag some of them.

6. Push the new commits and the tags.

Push similar to before, but ensure the [ ] Push all tags option in the push dialog is ticked as well.


A normal push does not include tags. After pushing the commits (as before), push tags to the repo as well:

To push a specific tag:

$ git push origin v1.0b

To push all tags:

$ git push origin --tags

You can push to repos other than the one you cloned from, as long as the target repo and your repo have a shared history.

  1. Add the GitHub repo URL as a remote, if you haven't done so already.
  2. Push to the target repo.

Push your repo to the new remote the usual way, but select the name of target remote instead of origin and remember to select the Track checkbox.


Push to the new remote the usual way e.g., git push upstream1 master (assuming you gave the name upstream1 to the remote).


You can even push an entire local repository to GitHub, to form an entirely new remote repository. For example, you created a local repo and worked with it for a while but now you want to upload it onto GitHub (as a backup or to share it with others). The steps are given below.

1. Create an empty remote repo on GitHub.

  1. Login to your GitHub account and choose to create a new Repo.

  2. In the next screen, provide a name for your repo but keep the Initialize this repo ... tick box unchecked.

  3. Note the URL of the repo. It will be of the form https://github.com/{your_user_name}/{repo_name}.git.
    e.g., https://github.com/johndoe/foobar.git (note the .git at the end)

2. Add the GitHub repo URL as a remote of the local repo. You can give it the name origin (or any other name).

3. Push the repo to the remote.


Push each branch to the new remote the usual way but use the -u flag to inform Git that you wish to the branch.
e.g., git push -u origin master



Phase 4: Working With Branches

In this phase, you'll learn how to use Git branches to track code changes done in parallel.

RCS: Branching

[Textbook location: Project Management → Revision Control → Branching]

Video

Can explain branching

Branching is the process of evolving multiple versions of the software in parallel. For example, one team member can create a new branch and add an experimental feature to it while the rest of the team keeps working on another branch. Branches can be given names e.g. master, release, dev.

A branch can be merged into another branch. Merging usually results in a new commit that represents the changes done in the branch being merged.

Branching and merging

Merge conflicts happen when you try to merge two branches that had changed the same part of the code and the RCS cannot decide which changes to keep. In those cases, you have to ‘resolve’ the conflicts manually.


Git: branch, merge

[Textbook location: Tools → Git and GitHub → branch: Doing multiple parallel changes]

Video

Can use Git branching

Git supports branching, which allows you to do multiple parallel changes to the content of a repository.

First, let us learn how the repo looks like as you perform branching operations.

A Git branch is simply a named label pointing to a commit. The HEAD label indicates which branch you are on. Git creates a branch named master by default. When you add a commit, it goes into the branch you are currently on, and the branch label (together with the HEAD label) moves to the new commit.

Given below is an illustration of how branch labels move as branches evolve. Refer to the text below it for explanations of each stage.

  1. There is only one branch (i.e., master) and there is only one commit on it. The HEAD label is pointing to the master branch (as we are currently on that branch).

    To learn a bit more about how labels such as master and HEAD work, you can refer to this article.

  2. A new commit has been added. The master and the HEAD labels have moved to the new commit.

  3. A new branch fix1 has been added. The repo has switched to the new branch too (hence, the HEAD label is attached to the fix1 branch).

  4. A new commit (c) has been added. The current branch label fix1 moves to the new commit, together with the HEAD label.

  5. The repo has switched back to the master branch. Hence, the HEAD has moved back to master branch's .
    At this point, the repo's working directory reflects the code at commit b (not c).

  1. A new commit (d) has been added. The master and the HEAD labels have moved to that commit.
  2. The repo has switched back to the fix1 branch and added a new commit (e) to it.
  3. The repo has switched to the master branch and the fix1 branch has been merged into the master branch, creating a merge commit f. The repo is currently on the master branch.

Now that you have some idea how the repo will look like when branches are being used, let's follow the steps below to learn how to perform branching operations using Git. You can use any repo you have on your computer (e.g. a clone of the samplerepo-things) for this.

0. Observe that you are normally in the branch called master.


$ git status

on branch master

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 (reason: Sourcetree automatically switches to the new branch when you create a new branch).


You can use the branch command to create a new branch and the checkout command to switch to a specific branch.

$ git branch feature1
$ git checkout feature1

One-step shortcut to create a branch and switch to it at the same time:

$ git checkout –b feature1

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.
Note how the master label and the HEAD label moves to the new commit (The HEAD label of the local repo is represented as in Sourcetree).

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.


$ git checkout master

4. Add a commit to the master branch. Let’s imagine it’s a bug fix.
To keep things simple for the time being, this commit should not involve the same content that you changed in the feature1 branch. To be on the safe side, you can change an entirely different file in this commit.

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 following. 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.


$ git merge master

The objective of that merge was to sync the feature1 branch with the master branch. 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.

To undo a merge,

  1. Ensure you are in the branch that received the merge.
  2. Do a hard reset (similar to how you delete a commit) of that branch to the commit that would be the tip of that branch had you not done the offending merge.

In the example below, you merged master to feature1.

If you want to undo that merge,

  1. Ensure you are in the feature1 branch.
  2. Reset the feature1 branch to the commit highlighted in the screenshot above (because that was the tip of the feature1 branch before you merged the master branch to it.

Instead of merging master to feature1, an alternative is to rebase the feature1 branch. However, rebasing is an advanced feature that requires modifying past commits. If you modify past commits that have been pushed to a remote repository, you'll have to force-push the modified commit to the remote repo in order to update the commits in it.

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....


$ git merge feature1

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:

Avoid this common rookie mistake!

Always remember to switch back to the master branch before creating a new branch. If not, your new branch will be created on top of the current branch.

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 following,

... 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:


Use the --no-ff switch (short for no fast forward):

$ git merge --no-ff add-countries


Git: Merge Conflicts

[Textbook location: Tools → Git and GitHub → Dealing with merge conflicts]

Video

Can use Git to resolve merge conflicts

Merge conflicts happen when you try to combine two incompatible versions (e.g., merging a branch to another but each branch changed the same part of the code in a different way).

Here are the steps to simulate a merge conflict and use it to learn how to resolve merge conflicts.

0. Create an empty repo or clone an existing repo, to be used for this activity.

1. Start a branch named fix1 in the 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 =======.

Highlighted below is the conflicting part that is coming from the master branch:

blue
<<<<<< HEAD
black
=======
green
>>>>>> fix1
red

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

blue
<<<<<< HEAD
black
=======
green
>>>>>> fix1
red

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. You have now successfully resolved the merge conflict.


Git: Remote Branches

[Textbook location: Tools → Git and GitHub → Working with remote branches]

Can work with remote branches

Git branches in a local repo can be linked to a branch in a remote repo so the local branch can 'track' the corresponding remote branch, and revision history contained in the local and the remote branch pair can be synchronized as desired.

[A] Pushing a new branch to a remote repo

Let's see how you can push a branch that you created in your local repo to the remote repo. Note that this branch does not exist in the remote repo yet.

Given below is how to push a branch named add-intro to your own fork named samplerepo-pr-practice.

We assume that your local repo already has the remote added to it with the name origin. If that is not the case, you should first configure your local repo to be able to communicate with the target remote repo.

  1. Click on Push button, which opens up the Push dialog.
  2. Choose the remote that you wish to push the branch (assuming you've added that repo to your Sourcetree already).
  3. Select the branch(es) you want to push -- in this case, add-intro.
    Ensure the Track? checkbox is ticked for the selected branch(es).
  4. Click Push.


$ git push -u origin add-intro

The -u (or --update) flag tells Git that you wish the local branch to 'track' the remote branch that will be created as a result of this push.

See git-scm.com/docs/git-push for details of the push command.


[B] Pulling a remote branch for the first time

Here, let's see how to fetch a new branch (i.e., it does not exist in your local repo yet) from a remote repo.

1. Check the list of remote branches by expanding the REMOTES menu on the left edge of Sourcetree. If the branch you expected to find is missing, you can click the Fetch button (in the top toolbar) to refresh the information shown under remotes.

2. Double-click the branch name (e.g., tweak-requirements branch in the myfork remote), which should open the checkout dialog shown below.

3. Go with the default settings (shown above) should be fine. Once you click OK, the branch will appear in your local repo. Furthermore, that repo will switch to that branch, and the local branch will the remote branch as well.


1. Fetch details from the remote. e.g., if the remote is named myfork

$ git fetch myfork

2. List the branches to see the name of the branch you want to pull.

$ git branch -a

master
remotes/myfork/master
remotes/myfork/branch1

-a flag tells Git to list both local and remote branches.

3. Create a matching local branch and switch to it.

$ git switch -c branch1 myfork/branch1

Switched to a new branch 'branch1'
branch 'branch1' set up to track 'myfork/branch1'.

-c flag tells Git to create a new local branch.


[C] Syncing branches

In this section we assume that you have a local branch that is already tracking a remote branch (e.g., as a result of doing [A] or [B] above).

To push new changes in the local branch to the corresponding remote branch:

Similar to how you pushed a new branch (in [A]):


Similar to [A] above, but omit the -u flag. e.g.,

$ git push origin add-intro

If you push but the remote branch has new commits that you don't have locally, Git will abort the push and will ask you to pull first.

To pull new changes from a remote branch to the corresponding local branch:

1. Switch to the branch you want to update by double-clicking the branch name. e.g.,

2. Pull the updated in the remote branch to the local branch by right-clicking on the branch name (in the same place as above), and choosing Pull <remote>/<branch> (tracked) e.g., Pull myfork/add-intro (tracked).


1. Switch to the branch you want to update using git checkout <branch> e.g.,

$ git checkout branch1

2. Pull the updated in the remote branch to the local branch, using git pull <remote> <branch> e.g.,

$ git pull origin branch1

If you pull but your local branch has new commits the remote branch doesn't have, Git will automatically perform a merge between the local branch and the remote branch.