Can create a local Git repo
Let's take your first few steps in your Git (with GitHub) 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:
2. Next, initialize a repository. Let us assume you want to version control content in a specific directory. In that case, you need to initialize a Git repository in that directory. Here are the steps:
Create a directory for the repo (e.g., a directory named
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. It is up to you 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 often called committing and a change saved to the revision history is called a commit.
Working directory: the root directory revision-controlled by Git (e.g., the directory in which the repo was initialized).
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.
Here are the steps you can follow to learn how to work with 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.
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.
Stage (verb): Instructing Git to prepare a file for committing.
4. Commit the staged version of
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 auto-creates a branch named
master on which the commits go on by default.
5. Do a few more commits.
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.
Next, add two more files
shapes.txtto the same working directory. Add a third commit to record the current state of the working directory.
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).
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. Tell Git to ignore that file:
.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
.gitignorefile 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
It supports file patterns e.g., adding
.gitignorefile prevents Git from tracking any
.tmpfiles in the
More information about the
.gitignore file: git-scm.com/docs/gitignore
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.,
Here's how you can tag a commit in a local repo (e.g. in the
After adding a tag to a commit, you can use the tag to refer to that commit, as an alternative to using the hash.
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
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:
Git repo URL:
https://github.com/se-edu/samplerepo-things.git (note the
.git at the end)
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.
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.
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
pull is a shortcut that does both those steps in one go.
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:
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
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.
- Add the GitHub repo URL as a remote, if you haven't done so already.
- Push to the target repo.
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.
Login to your GitHub account and choose to create a new Repo.
In the next screen, provide a name for your repo but keep the
Initialize this repo ...tick box unchecked.
Note the URL of the repo. It will be of the form
.gitat 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.
Can use Git branching
Git supports branching, which allows you to do multiple parallel changes to the content of a repository.
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.
- There is only one branch (i.e.,
master) and there is only one commit on it.
- A new commit has been added. The
HEADlabels have moved to the new commit.
- A new branch
fix1has been added. The repo has switched to the new branch too (hence, the
HEADlabel is attached to the
- A new commit (
c) has been added. The current branch label
fix1moves to the new commit, together with the
- The repo has switched back to the
- A new commit (
d) has been added. The
masterlabel has moved to that commit.
- The repo has switched back to the
fix1branch and added a new commit (
e) to it.
- The repo has switched to the
masterbranch and the
fix1branch has been merged into the
masterbranch, creating a merge commit
f. The repo is currently on the
Follow the steps below to learn how to work with branches. 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
1. Start a branch named
feature1 and switch to the new branch.
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.
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, this commit can change an entirely different file.
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.
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
Instead of merging
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
8. Switch to the
master branch and add one more commit.
feature1 to the master branch, giving and end-result like this:
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.
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
blue <<<<<< HEAD black ======= green >>>>>> fix1 red
This is the conflicting part that is coming from the
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.
Can create PRs on GitHub
Suppose you want to propose some changes to a GitHub repo (e.g., samplerepo-pr-practice) as a pull request (PR). Here is a scenario you can try in order to learn how to create PRs:
1. Fork the repo onto your GitHub account.
2. Clone it onto your computer.
3. Commit your changes e.g., add a new file with some contents and commit it.
- Option A - Commit changes to the
- Option B - Commit to a new branch e.g., create a branch named
add-intro(remember to switch to the
masterbranch before creating a new branch) and add your commit to it.
4. Push the branch you updated (i.e.,
master branch or the new branch) to your fork, as explained here.
5. Initiate the PR creation:
Go to your fork.
Click on the Pull requests tab followed by the New pull request button. This will bring you to the 'Comparing changes' page.
Set the appropriate target repo and the branch that should receive your PR, using the
base repository: se-edu/samplerepo-pr-practice base: master
Normally, the default value shown in the dropdown is what you want but in case your fork has e.g., the repo you forked from is also a fork of a another repo, which means both of those are considered upstream repos of your forkmultiple upstream repos, the default may not be what you want.
Indicate which repo:branch contains your proposed code, using the
head repository: myrepo/samplerepo-pr-practice compare: master
6. Verify the proposed code: Verify that the diff view in the page shows the exact change you intend to propose. If it doesn't, commit the new code and push to the branchupdate the branch as necessary.
7. Submit the PR:
Click the Create pull request button.
Fill in the PR name and description e.g.,
Add an introduction to the README.md
Add some paragraph to the README.md to explain ... Also add a heading ...
If you want to indicate that the PR you are about to create is 'still work in progress, not yet ready', click on the dropdown arrow in the Create pull request button and choose
Create draft pull requestoption.
Click the Create pull request button to create the PR.
Go to the receiving repo to verify that your PR appears there in the
The next step of the PR life cycle is the PR review. The members of the repo that received your PR can now review your proposed changes.
- If they like the changes, they can merge the changes to their repo, which also closes the PR automatically.
- If they don't like it at all, they can simply close the PR too i.e., they reject your proposed change.
- In most cases, they will add comments to the PR to suggest further changes. When that happens, GitHub will notify you.
You can update the PR along the way too. Suppose PR reviewers suggested a certain improvement to your proposed code. To update your PR as per the suggestion, you can simply modify the code in your local repo, commit the updated code to the same
master branch, and push to your fork as you did earlier. The PR will auto-update accordingly.
Sending PRs using the
master branch is less common than sending PRs using separate branches. For example, suppose you wanted to propose two bug fixes that are not related to each other. In that case, it is more appropriate to send two separate PRs so that each fix can be reviewed, refined, and merged independently. But if you send PRs using the
master branch only, both fixes (and any other change you do in the
master branch) will appear in the PRs you create from it.
To create another PR while the current PR is still under review, create a new branch (remember to switch back to the
master branch first), add your new proposed change in that branch, and create a new PR following the steps given above.
It is possible to create PRs within the same repo e.g., you can create a PR from branch
feature-x to the
master branch, within the same repo. Doing so will allow the code to be reviewed by other developers (using PR review mechanism) before it is merged.
Can review PRs on GitHub
The PR review stage is a dialog between the PR author and members of the repo that received the PR, in order to refine and eventually merge the PR.
Given below are some steps you can follow when reviewing a PR.
1. Locate the PR:
- Go to the GitHub page of the repo.
- Click on the Pull requests tab.
- Click on the PR you want to review.
2. Read the PR description. It might contain information relevant to reviewing the PR.
3. Click on the Files changed tab to see the diff view.
4. Add review comments:
- 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.
To mark multiple lines, click-and-drag the icon.
- Enter your comment.
This page @SE-EDU/guides has some best practices PR reviewers can follow.
- After typing in the comment, click on the Start a review button (not the Add single comment button. This way, your comment is saved but not visible to others yet. It will be visible to others only when you have finished the entire review.
- Repeat the above steps to add more comments.
5. Submit the review:
- When there are no more comments to add, click on the Review changes button (on the top right of the diff page).
- Type in an overall comment about the PR, if any. e.g.,
Overall, I found your code easy to read for the most part except a few places where the nesting was too deep. I noted a few minor coding standard violations too. Some of the classes are getting quite long. Consider splitting into smaller classes if that makes sense.
LGTMis often used in such overall comments, to indicate
Looks good to merge.
nitis another such term, used to indicate minor flaws e.g.,
LGTM, almost. Just a few nits to fix..
Request changesoption as appropriate and click on the Submit review button.
Can review and merge PRs on GitHub
Let's look at the steps involved in merging a PR, assuming the PR has been reviewed, refined, and approved for merging already.
Preparation: If you would like to try merging a PR yourself, you can create a dummy PR in the following manner.
- Fork any repo (e.g., samplerepo-pr-practice).
- Clone in to your computer.
- Create a new branch e.g., (
feature1) and add some commits to it.
- Push the new branch to the fork.
- Create a PR from that branch to the
masterbranch in your fork. Yes, it is possible to create a PR within the same repo.
1. Locate the PR to be merged in your repo's GitHub page.
2. Click on the Conversation tab and scroll to the bottom. You'll see a panel containing the PR status summary.
3. If the PR is not merge-able in the current state, the Merge pull request will not be green. Here are the possible reasons and remedies:
- Problem: The PR code is out-of-date, indicated by the message This branch is out-of-date with the base branch. That means the repo's
masterbranch has been updated since the PR code was last updated.
- If the PR author has allowed you to update the PR and you have sufficient permissions, GitHub will allow you to update the PR simply by clicking the Update branch on the right side of the 'out-of-date' error message. If that option is not available, post a message in the PR requesting the PR author to update the PR.
- Problem: There are merge conflicts, indicated by the message This branch has conflicts that must be resolved. That means the repo's
masterbranch has been updated since the PR code was last updated, in a way that the PR code conflicts with the current
masterbranch. Those conflicts must be resolved before the PR can be merged.
- If the conflicts are simple, GitHub might allow you to resolve them using the Web interface.
- If that option is not available, post a message in the PR requesting the PR author to update the PR.
3. Merge the PR by clicking 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.
- You can choose between three merging options by clicking on the down-arrow in the Merge pull request button. If you are new to Git and GitHub, the
Create merge commitoptions are recommended.
Next, sync your local repos (and forks). Merging a PR simply merges the code in the upstream remote repository in which it was merged. The PR author (and other members of the repo) needs to pull the merged code from the upstream repo to their local repos and push the new code to their respective forks to sync the fork with the upstream repo.
Can follow Forking Workflow
You can follow the steps in the simulation of a forking workflow given below to learn how to follow such a workflow.
This activity is best done as a team.
Step 1. One member: set up the team org and the team repo.
Create a GitHub organization for your team. The org name is up to you. We'll refer to this organization as team org from now on.
Add a team called
developersto your team org.
Add team members to the
Fork se-edu/samplerepo-workflow-practice to your team org. We'll refer to this as the team repo.
Add the forked repo to the
developersteam. Give write access.
Step 2. Each team member: create PRs via own fork.
Fork that repo from your team org to your own GitHub account.
Create a branch named
add-johnTan-info) in the local repo.
Add a file
members/jonhTan.md) containing some info about you into that branch.
Push that branch to your fork.
Create a PR from that branch to the
masterbranch of the team repo.
Step 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] Approve and 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.
Step 4. Create conflicting PRs.
[One member]: Update README: In the
masterbranch, remove John Doe and Jane Doe from the
README.md, commit, and push to the main repo.
[Each team member] Create a PR to add yourself under the
Team Memberssection in the
README.md. Use a new branch for the PR e.g.,
Step 5. Merge conflicting PRs one at a time. Before merging a PR, you’ll have to resolve conflicts.
[Optional] A member can inform the PR author (by posting a comment) that there is a conflict in the PR.
[PR author] Resolve the conflict locally:
- Pull the
masterbranch from the repo in your team org.
- Merge the pulled
masterbranch to your PR branch.
- Resolve the merge conflict that crops up during the merge.
- Push the updated PR branch to your fork.
- Pull the
[Another member or the PR author]: Merge the de-conflicted PR: When GitHub does not indicate a conflict anymore, you can go ahead and merge the PR.