Difference between revisions of "Basic Git Tutorial"

From Embedded Systems Learning Academy
Jump to: navigation, search
(Examples)
(PULL)
 
(66 intermediate revisions by 4 users not shown)
Line 1: Line 1:
'''Work In Progress'''
 
 
 
 
I will be focusing on the command line for Git and not the GUI. I will also be focusing on Git Lab because that is our class’s main focus.
 
  
  
 +
Git uses the concept of branches where multiple people could work on different parts of a project at the same time. Eventually they could merge all their work together to create a complete project. They could also work on it some more should their be a need for bug fixes, updates, etc. Developers can pick and choose what features they want to add or remove and can see a log of the work done and changes made by their peers.
 +
In this tutorial, I will be focusing on the command line for Git and not the GUI. I will also be focusing on Git Lab because that is our class’s main focus. This tutorial is not comprehensive but it will give a very basic overview of Git commands. There are many different kinds of commands, but only a few need to be used.
  
 
Anything within “< >” is an option.
 
Anything within “< >” is an option.
 
  
  
Line 17: Line 13:
 
Download the Git program here. [https://git-scm.com/downloads https://git-scm.com/downloads]
 
Download the Git program here. [https://git-scm.com/downloads https://git-scm.com/downloads]
  
You will now be able use it via command line, or with the GUI. It is suggested that you use the command line, as there are more features. To use the Windows command line, go to the start menu -> type “cmd” -> enter. If you wish to use a nicer version of the Windows command line, it is suggested you download ConEmu available here [http://www.fosshub.com/ConEmu.html http://www.fosshub.com/ConEmu.html].
+
You will now be able use it via command line, or with the GUI. It is suggested that you use the command line, as there are more features. To use the Windows command line, go to the start menu -> type “cmd” -> enter. It is highly suggested that you use ConEmu in place of the default Windows command prompt. There are more options for Git and is easier to work with.  Download it here: [http://www.fosshub.com/ConEmu.html http://www.fosshub.com/ConEmu.html].
 
 
  
  
If Git does not work on ConEmu, then make sure the options matches the one in the picture. Access options by “windows key + alt + p”.  Go to Startup -> tasks and then press the ‘+’ button. Now name it “Git Bash” and then type in the bottom box:  
+
If Git does not work on ConEmu, then make sure the options matches the one in the picture. Access options by “windows key + alt + p”.  Go to Startup -> tasks and then press the ‘+’ button. Now name it “Git Bash” and then type in the bottom box and make sure it looks like the picture shown below:  
  
 
<center>"C:\Program Files\Git\bin\<nowiki>sh.ex</nowiki>e" --login –I</center>
 
<center>"C:\Program Files\Git\bin\<nowiki>sh.ex</nowiki>e" --login –I</center>
Line 27: Line 22:
 
<center></center>
 
<center></center>
  
<center>PICTURE HERE</center>
+
[[Image:GitTutorial ConEmu Setup.JPG|center|500px]]
  
 
<center></center>
 
<center></center>
  
Do not touch the parameter box.  Press Save. You will now be able to access Git in a new cmd window. Press the drop down menu button near the green ‘+’ button. Press the {Git Bash} option. You are now ready to use Git.  
+
Do not touch the parameter box.  Press Save. You will now be able to access Git in a new cmd window. Press the drop down menu button near the green ‘+’ button. Press the {Git Bash} option. You are now ready to use Git. Your terminal should look something like this:
 
 
  
 +
[[Image:GitTutorial_ConEmu.JPG‎|center|500px]]
  
The first thing we will do is set up our SSH key. In this section we till talk about init and clone. None of these deal with uploading and making changes. That will be discussed in the collaboration section.
 
  
 
+
'''Setting up SSH key'''
 
 
''Setting up SSH key''
 
  
 
Go to <nowiki>www.gitlab.com</nowiki> -&gt; Profile settings -&gt; Add SSH Key -&gt; Now open up terminal and type in:
 
Go to <nowiki>www.gitlab.com</nowiki> -&gt; Profile settings -&gt; Add SSH Key -&gt; Now open up terminal and type in:
  
{| class="prettytable"
+
{| class="wikitable"
 +
|-
 +
! scope="col"| Command
 +
! scope="col"| Description
 
|-
 
|-
 
|
 
|
Line 66: Line 61:
  
  
''Setting a new Git Repository''
+
'''Setting a new Git Repository'''
  
 
If you are working on an existing remote repository, then this part is unnecessary. However, if you are working on something, and there is no Git repository, then you must set up a new project on the Git website.  
 
If you are working on an existing remote repository, then this part is unnecessary. However, if you are working on something, and there is no Git repository, then you must set up a new project on the Git website.  
Line 86: Line 81:
  
  
''Setting it up on Eclipse''
+
'''Setting it up on Eclipse'''
  
PICTURE HERE
+
Currently, many people, myself included, are having issues with SSH in Eclipse, but I will go ahead and give instructions on how to set it up. Get your .ssh directory by typing in ConEmu "cd ~/.ssh" -> "pwd". Take that directory and go into the Eclipse's preferences. Go to General -> Network Connections -> SSH2 -> Input your .ssh directory and then Add private key (id_rsa, id_rsa.pub).
  
 +
[[Image:GitTutorial EclipseSSH.JPG|center|700px]]
  
 +
More instructions can be found on using Gitlab with Eclipse here: http://www.socialledge.com/sjsu/index.php?title=Eclipse_%26_Gitlab_Tutorial
  
 
'''Commands'''
 
'''Commands'''
Line 100: Line 97:
  
  
{| class="prettytable"
+
{| class="wikitable"
 +
|-
 +
! scope="col"| Command
 +
! scope="col"| Description
 
|-
 
|-
 
|
 
|
Line 121: Line 121:
  
  
{| class="prettytable"
+
{| class="wikitable"
 +
|-
 +
! scope="col"| Command
 +
! scope="col"| Description
 
|-
 
|-
 
|
 
|
Line 135: Line 138:
 
|}
 
|}
  
== Collaboration ==
+
== Workflow ==
 +
 
 +
=== Introduction ===
 +
 
 +
In Git there is the notion of a "Master" code base which contains the work of all contributing members in a project.
 +
 
 +
There are two basic workflows that you may follow when using Git for version control.
 +
 
 +
:  1. Committing directly to the "Master" branch.
 +
:  2. Creating branches from the "Master" branch and merging them back in when ready.
  
Once you’ve worked on the code and you wish to upload your work to the server, you must first “add” the current snapshot of your work to the index, and then “commit” it. After doing these tasks, “push” your work onto the master. If the master has been updated with someone else’s code, you may pull it to fetch and merge your repository.
+
This section of the guide will walk you through these two workflow strategies.  
  
 +
=== Working off the "Master" Branch ===
  
 +
[[File:git_tut_master_branch.png|center|500px]]
  
 +
Working directly off the "Master" branch can be advantageous to smaller groups who rarely (if ever) work on the same portions of the code at a time.
  
 +
[[File:git_tut_local_master.PNG|center|500px]]
  
'''Uploading commands'''
+
The basic workflow for this method is as follows:
  
''ADD''
+
:  1. "Pull" from Master branch to ensure the local copy contains the latest version of code.
 +
:  2. Make necessary changes to code.
 +
:  3. Commit your changes.
 +
:  4. "Push" your changes to the remote repository.
  
When you feel like you’ve made changes that you wish to upload to the master, you must first “add” your code. Adding your code puts the current snapshot of your work into the index. This is a local command and does not add anything to the server yet.
+
In git commands this would look like:
  
 +
<source lang="bash">
 +
# Make sure you are on master branch
 +
git checkout master
 +
# Make sure you have the latest code
 +
git pull origin master
 +
# Make your changes to your code
 +
# Add files you may have changed to your commit
 +
git add <file1> <file2> ...
 +
# Commit your changes
 +
git commit -m "<commit message here>"
 +
# Push your changes
 +
git push origin HEAD
 +
</source>
  
 +
As you can see, this workflow is quite simplistic. There are; however, some key disadvantages to this workflow. If group members begin to modify the same files at the same time then they will face merge conflicts when attempting to push their code to the remote repository. Furthermore, you will not be able to work on different features at the same time and you are essentially stuck with "one" version of the master branch.  Merge conflicts occur when code that is committed conflicts with changes that were made to the target branch while you were making your own changes. For example:
  
If you created your repository, and it has not yet been uploaded, then use “git remote add”. This will communicate your repository to the git server. This still does not upload your repository.
+
:  1. Developer A pulls the Master branch
 +
:  2. Developer B pulls the Master branch
 +
:  3. Developer B makes changes to file A and pushes the code back into the remote Master branch
 +
:  4. Developer A makes changes to file A and pushes the code back into the remote Master branch
  
{| class="prettytable"
+
Developer A will experience a merge conflict since he/she is modifying a file that has already changed in the remote repo.
|-
 
|
 
git add &lt;directory/file&gt;
 
  
|
+
=== Working with feature branches ===
Adds snapshot of current code to index
 
  
|-
+
The second workflow takes advantage of the branching system in git. To protect your Master branch from code which may break your build or introduce bugs we can create what is called a "feature branch." These branches contain your development code and isolates it from the main code until you are ready to merge them together.
|
 
git remote add origin &lt;git url&gt;
 
  
|
+
The workflow is as follows:
Adds remote to existing repository
 
  
|}
+
:  1. Do a "git fetch" to obtain the latest version of your source branch
 +
:  2. Checkout a new branch
 +
:  3. Perform your work on your new branch (be sure to make regular commits to avoid losing any of your work.)
 +
:  4. Merge the two branches
  
 +
Here is the general workflow in git commands:
  
 +
<source lang="bash">
 +
# Checkout your "source" branch (the branch you want to base your code off of)
 +
git checkout master
 +
# Obtain the latest code
 +
git pull origin master
 +
# Create a new branch from your source branch
 +
git checkout -b <new branch name>
 +
# Make your code changes and commit them regularly
 +
git add <file1> <file2> ...
 +
git commit -m "<commit message>"
  
 +
# Push your changes to your FEATURE branch
 +
# GIT server knows this branch after the push and other people can also check-out your branch
 +
# But this branch is not yet merged to the master branch
 +
git push origin HEAD
 +
</source>
  
''COMMIT''
+
[[FILE:git_tut_feature_merge.png|center|500px|thumb|Purple: feature branch, White: source branch, After merge the source branch contains all code from the feature branch]]
  
After adding your work, you must “commit” it. If you don’t commit and you try to push, you may receive an error saying that you must first commit. Committing your work puts your work’s index into the Head. Committing is essentially a history log about changes made. When you commit you include a message saying what changes you made so others can see it as well. Other developers can see the changes you made, and you can see the changes they made. After committing, you are ready to push your work onto the master
+
When you are ready to merge your branch back into the source branch there are two routes you may take:
  
{| class="prettytable"
+
:  1. Merge your feature branch directly into the source branch.
|-
+
:  2. Open a pull request for peer code review prior to merging you branch.
|
 
git commit –m “My changes…”
 
  
|
+
To merge your feature branch into the source use the following workflow:
Pushes your work from index to the head. ‘-m’ allows you to write a messages. Make sure the message is meaningful so that others can understand it.
+
:  1. Checkout the source branch
 +
:  2. Ensure your source branch contains the most updated code from the remote repo
 +
:  3. Merge your feature branch into the source branch
 +
:  4. Push the newly merged source branch back to the remote repo
  
|}
+
The git commands for this workflow looks like this:
 +
<source lang="bash">
 +
# Checkout the source branch that you want to merge your branch into (assuming your source was 'master')
 +
git checkout master
 +
# Ensure your source branch is up-to-date
 +
git pull origin master
 +
# Merge your feature branch INTO the source branch
 +
git merge <feature branch>
  
 +
# At this point, you might need to resolve merge conflicts
  
 +
# Push your changes to the remote repo
 +
git push origin master
 +
</source>
  
 +
== Commands ==
  
''PUSH''
+
=== Basic Commands ===
 +
In the above workflow examples we saw some of the basic commands that you will use in your development workflow. In this section we will explore some of these commands in more detail.
  
After adding and committing your work, you can now push onto the master. This will make changes in the master and everyone may now pull the updated master to their repositories with the changes you’ve made. Because you’ve committed, people can now view the messages and changes you’ve made to the code.
+
==== ADD ====
  
 +
<source lang="bash">
 +
# This command adds untracked or modified files to be committed. If you do not add changed files to your commit then git will not track that file and save its changes.
 +
git add <file1> <file2> ....
 +
</source>
  
 +
==== RESET ====
  
{| class="prettytable"
+
<source lang="bash">
|-
+
# Reset has a number of different uses and is incredibly versatile.
|
+
# If you accidentally add a file to be committed and have not used the 'git commit' command you can remove it from the commit using this command
git push origin master
+
git reset HEAD <file1> <file2> ...
  
|
+
# If you would like to revert to a previous commit, but save all the work you may use this command:
Pushes your local repository to remote server
+
git log
  
|}
+
# Choose the proper git hash to revert to
 +
git reset --soft <git hash>
  
 +
# The following command is EXTREMELY powerful, and you should only use it if you are sure about what you are doing.
 +
# If you would like to revert to a previous commit, but LOSE all your work you may use this command:
 +
git log
  
 +
# Choose the proper git hash
 +
git reset --hard <git hash>
 +
</source>
  
 +
==== COMMIT ====
  
'''Downloading commands'''
+
<source lang="bash">
 +
# Committing your work is essential to saving your work and is the heart of git
 +
# First add all files you would like to add to your commit using the 'git add' command listed above
  
''PULL''
+
# Using the '-m' option will allow you to enter the commit message in a single command
 +
git commit -m "<commit message>"
  
To update your current repository with a newer one, use the “pull” command.  This command updates the current repository with the current version on the Git server. Pull is different from clone in that it fetches and merges the repository to your local repository, that way you can continue working. Cloning does not do this, and you get a completely new repository.
+
# Using the commit command without any operators will allow you to enter a much more detailed commit message through the vim editor
 +
git commit
 +
</source>
  
== Branches ==
+
When using the 'vim' editor there are some basic things you will need to know about.
'''BRANCH'''
+
*There is a 'command' mode and an 'insert' mode
 +
**Command mode is where you can use commands such as save and exit or search text
 +
**Insert mode allows you to do text editing
 +
*Vim always starts in command mode
 +
**To enter insert mode press the 'i' button on your keyboard
 +
**Enter your commit message
 +
*To exit you must return to command mode by pressing the 'ESCAPE' button
 +
**To exit you may use the following commands:
 +
*** :q - Exit without saving if no changes were made
 +
*** :q! - Exit without saving even if changes were made
 +
*** :x - Save and exit
  
'''CHECKOUT'''
+
[https://linuxconfig.org/vim-tutorial A good resource on how to use VIM]
  
'''FINISH THIS PAGE'''
+
==== PUSH ====
  
== Examples ==
+
<source lang="bash">
 +
# After creating your commit you will want to 'push' your changes to the remote server.
 +
# If you do not push your changes then they will not be saved to the server and any data loss will result in loss of work.
 +
git push origin HEAD
 +
</source>
  
 +
==== FETCH ====
  
 +
<source lang="bash">
 +
# Your local repo will not know about commits or branches that happen on the remote server until you update your local machine
 +
git fetch
 +
</source>
  
'''Starting a new repository'''
+
==== MERGE ====
 +
<source lang="bash">
 +
# You can merge a target branch into a source branch to bring in all of the code into your source branch
 +
# Checkout the branch you want to merge code INTO
 +
git checkout <branch name>
  
''<nowiki>www.gitlab.com</nowiki>''
+
# Ensure that your branch is up-to-date
 +
git pull
  
''Add project''
+
# Pull the code from the target branch into your current branch
 +
git merge <target branch name>
 +
</source>
  
''Create Project''
+
==== PULL ====
 +
<source lang="bash">
 +
# Pull can be a good way to update your current local branch to where the remote branch is.
 +
# For example if you had checked out the master branch some time ago, but others have pushed new commits to the
 +
# remote branch you will need to update your local branch.
  
 +
# The pull command is actually a combination of the two commands above 'fetch' and 'merge'
 +
# It will fetch first to obtain information on all of the new remote changes then merge those changes
 +
# into your local copy
 +
git pull
 +
</source>
  
git init
+
==== CHECKOUT ====
 +
<source lang="bash">
 +
# The checkout command allows you to switch to a different branch as well as create new branches.
  
git add .
+
# To switch to a different branch you may do the following:
 +
git checkout <branch name>
  
git commit –m “First Commit”
+
# If the branch does not exist in your local repo you will need to run the 'git fetch'
 +
# command in order to switch to it.
  
git remote add origin git@<nowiki>gitlab.com</nowiki>:username/<nowiki>projectname.gi</nowiki>t
+
# If the branch does not exist AT ALL you may create a new branch using the following command:
 +
git checkout -b <new branch name>
 +
</source>
  
get remote –v
+
==== STATUS ====
 +
<source lang="bash">
 +
# The status command will provide you with the current status of your branch. It provides information
 +
# such as files changed or whether or not you are up-to-date with the remote branch.
 +
git status
 +
</source>
  
git push origin master
+
=== DIFF ===
 +
<source lang="bash">
 +
# Diff allows you to compare your current workspace with a different git hash. If you have made any
 +
# changes to your tracked files then git will show you exactly what has changed.
  
 +
# To show the diff between your working copy and the most recent committed git hash you may use this:
 +
git diff
  
 +
# If you would like to compare your working copy with a different git hash you may use:
 +
git diff <git hash>
 +
</source>
  
''People will now be able to make changes to your code. ''
+
=== Advanced Commands ===
  
 +
==== REBASE ====
  
 +
<source lang="bash">
 +
# Rebasing is an EXTREMELY powerful tool which essentially rewrites history. Rebase will allow you to squash commits
 +
# together and even change the source branch which you originally branched off from.
  
'''Cloning'''
+
# When using rebase you can squash any number of commits so you must be careful with how many commits you are squashing.
 +
# First use 'git log' to see what commits you would like to squash
 +
git log
  
''You see a code you want to work with, so you will clone it into your current directory.''
+
# Say you want to squash two commits. You may use
 +
git rebase -i HEAD~2
  
Git clone git@<nowiki>gitlab.com</nowiki>:username/<nowiki>projectname.gi</nowiki>t
+
# In the vim editor that pops up you may choose different options for each commit.
 +
# Remember that the commits will be applied in order from the top down.
  
 +
# It is possible to change your branch's source branch using this command.
 +
# If you would like to place all of your branch's commits on top of the latest source branch you can do something like this:
  
'''Pushing'''
+
# Checkout the source branch (assume source is 'master')
 +
git checkout master
  
''After working for some time on a code, you’ve made some changes. Now, you want to push it to master''
+
# Update your source branch
 +
git pull origin master
  
git add .
+
# Return to your feature branch (the dash means return to previously checked out branch)
 +
git checkout -
  
git commit –m “Commit comment.”
+
# Rebase onto the newly updated source branch
 +
git rebase -i master
 +
</source>
  
git push origin master
+
==== FORCE PUSH ====
 +
<source lang="bash">
 +
# After rebasing you will need to push your changes to the remote repo. Normally git will see that your history no longer
 +
# matches with that of the server's. It will then prevent you from pushing. It is possible to get around this through the
 +
# use of 'force pushing'
  
 +
# You must be VERY careful when force pushing since you are rewriting history for EVERYONE. If anyone has a local copy of
 +
# the branch you are force pushing to, they will run into issues if they try to push their own version of the branch to
 +
# the server.
  
''If you wish to push to a different branch''
+
git push -f origin HEAD
  
git push origin branchname
+
</source>
  
  
'''Pulling'''
+
==== CHERRY-PICKING ====
 +
<source lang="bash">
 +
# Cherry-picking allows you to hand pick certain commits to add onto the top of your branch
 +
git cherry-pick <git hash>
 +
</source>
  
''Teammates made some changes to the code.''
+
== Merge Conflicts ==
  
''Time to update your repository.''
+
When working in a team it will be inevitable that the same file will be touched by multiple developers. If multiple make changes in the same part of the file then it will result in a merge conflict when attempting to merge the files together. These conflicts can be resolved in your IDE directly or in any text editor.
  
git pull origin master
+
== More Information ==
  
 +
Remember this page only provides a brief overview of the most basic commands. Git is extremely powerful and every command has multiple options. Please reference the links below to learn about other actions you can take in git.
  
 +
[https://www.atlassian.com/git/tutorials/comparing-workflows Git tutorial]
  
ADD BRANCH EXAMPLE
+
[https://git-scm.com/doc  Offical Git documentation]

Latest revision as of 05:41, 17 October 2016


Git uses the concept of branches where multiple people could work on different parts of a project at the same time. Eventually they could merge all their work together to create a complete project. They could also work on it some more should their be a need for bug fixes, updates, etc. Developers can pick and choose what features they want to add or remove and can see a log of the work done and changes made by their peers. In this tutorial, I will be focusing on the command line for Git and not the GUI. I will also be focusing on Git Lab because that is our class’s main focus. This tutorial is not comprehensive but it will give a very basic overview of Git commands. There are many different kinds of commands, but only a few need to be used.

Anything within “< >” is an option.


Getting Started

Download the Git program here. https://git-scm.com/downloads

You will now be able use it via command line, or with the GUI. It is suggested that you use the command line, as there are more features. To use the Windows command line, go to the start menu -> type “cmd” -> enter. It is highly suggested that you use ConEmu in place of the default Windows command prompt. There are more options for Git and is easier to work with. Download it here: http://www.fosshub.com/ConEmu.html.


If Git does not work on ConEmu, then make sure the options matches the one in the picture. Access options by “windows key + alt + p”. Go to Startup -> tasks and then press the ‘+’ button. Now name it “Git Bash” and then type in the bottom box and make sure it looks like the picture shown below:

"C:\Program Files\Git\bin\sh.exe" --login –I
GitTutorial ConEmu Setup.JPG

Do not touch the parameter box. Press Save. You will now be able to access Git in a new cmd window. Press the drop down menu button near the green ‘+’ button. Press the {Git Bash} option. You are now ready to use Git. Your terminal should look something like this:

GitTutorial ConEmu.JPG


Setting up SSH key

Go to www.gitlab.com -> Profile settings -> Add SSH Key -> Now open up terminal and type in:

Command Description

ssh-keygen -t rsa -C "youremail@email.com"

cat ~/.ssh/id_rsa.pub

Generates the key

Shows your key


After concatenating the key, copy and paste the SSH key into the “Key” box. If you are on windows and can’t copy paste type in: clip < ~/.ssh/id_rsa.pub


Your SSH Key is now set up.


Setting a new Git Repository

If you are working on an existing remote repository, then this part is unnecessary. However, if you are working on something, and there is no Git repository, then you must set up a new project on the Git website.


Setting up a new project is simple on Git Lab. Simply go to www.gitlab.com and then click on the green button that says “Add Project”. Type in your project name in the “Project path” box. Add any descriptions about your project. Although it is optional, it is highly suggested you briefly describe your project. Press Create Project once done.


Your project path will now look something like this “https://gitlab.com/username/projectname”. From here, anyone can grab your project via SSH or HTTPS.

SSH path example: git@gitlab.com:username/projectname.git

HTTPS path example: https://gitlab.com/username/projectname.git

See the example on how to upload your local repository to the server.


Setting it up on Eclipse

Currently, many people, myself included, are having issues with SSH in Eclipse, but I will go ahead and give instructions on how to set it up. Get your .ssh directory by typing in ConEmu "cd ~/.ssh" -> "pwd". Take that directory and go into the Eclipse's preferences. Go to General -> Network Connections -> SSH2 -> Input your .ssh directory and then Add private key (id_rsa, id_rsa.pub).

GitTutorial EclipseSSH.JPG

More instructions can be found on using Gitlab with Eclipse here: http://www.socialledge.com/sjsu/index.php?title=Eclipse_%26_Gitlab_Tutorial

Commands

INIT

The first thing you want to do before you init is to add a project in the Git website see “Setting up a new Git repository” section. If you have a folder with code that is not on Git, and you wish to put it on the Git server, then you need to initialize Git into your folder. This creates a .git folder, and the current directory is now a Git repository. The .git folder contains Git information such as branches. Initializing your folder is local to your computer and is not yet uploaded onto the server.


Command Description

git init

git init <directory>

Initialize current directory

Initialize selected directory


CLONE

If you see a repository that you want to work on, you can “clone” it into a directory and start working on it. Cloning it will download the entire repository as well as a .git folder. Note that clone is different from “pull”. This will be explained later. Just use this command once at the beginning of the project unless you want multiple folders.


Command Description

git clone <repo>

git clone <repo> <directory>

Downloads entire repository to current directory

Downloads entire repository to selected directory

Workflow

Introduction

In Git there is the notion of a "Master" code base which contains the work of all contributing members in a project.

There are two basic workflows that you may follow when using Git for version control.

1. Committing directly to the "Master" branch.
2. Creating branches from the "Master" branch and merging them back in when ready.

This section of the guide will walk you through these two workflow strategies.

Working off the "Master" Branch

Git tut master branch.png

Working directly off the "Master" branch can be advantageous to smaller groups who rarely (if ever) work on the same portions of the code at a time.

Git tut local master.PNG

The basic workflow for this method is as follows:

1. "Pull" from Master branch to ensure the local copy contains the latest version of code.
2. Make necessary changes to code.
3. Commit your changes.
4. "Push" your changes to the remote repository.

In git commands this would look like:

# Make sure you are on master branch
git checkout master
# Make sure you have the latest code
git pull origin master
# Make your changes to your code
# Add files you may have changed to your commit
git add <file1> <file2> ...
# Commit your changes
git commit -m "<commit message here>"
# Push your changes
git push origin HEAD

As you can see, this workflow is quite simplistic. There are; however, some key disadvantages to this workflow. If group members begin to modify the same files at the same time then they will face merge conflicts when attempting to push their code to the remote repository. Furthermore, you will not be able to work on different features at the same time and you are essentially stuck with "one" version of the master branch. Merge conflicts occur when code that is committed conflicts with changes that were made to the target branch while you were making your own changes. For example:

1. Developer A pulls the Master branch
2. Developer B pulls the Master branch
3. Developer B makes changes to file A and pushes the code back into the remote Master branch
4. Developer A makes changes to file A and pushes the code back into the remote Master branch

Developer A will experience a merge conflict since he/she is modifying a file that has already changed in the remote repo.

Working with feature branches

The second workflow takes advantage of the branching system in git. To protect your Master branch from code which may break your build or introduce bugs we can create what is called a "feature branch." These branches contain your development code and isolates it from the main code until you are ready to merge them together.

The workflow is as follows:

1. Do a "git fetch" to obtain the latest version of your source branch
2. Checkout a new branch
3. Perform your work on your new branch (be sure to make regular commits to avoid losing any of your work.)
4. Merge the two branches

Here is the general workflow in git commands:

# Checkout your "source" branch (the branch you want to base your code off of)
git checkout master
# Obtain the latest code
git pull origin master
# Create a new branch from your source branch
git checkout -b <new branch name>
# Make your code changes and commit them regularly
git add <file1> <file2> ...
git commit -m "<commit message>"

# Push your changes to your FEATURE branch
# GIT server knows this branch after the push and other people can also check-out your branch
# But this branch is not yet merged to the master branch
git push origin HEAD
Purple: feature branch, White: source branch, After merge the source branch contains all code from the feature branch

When you are ready to merge your branch back into the source branch there are two routes you may take:

1. Merge your feature branch directly into the source branch.
2. Open a pull request for peer code review prior to merging you branch.

To merge your feature branch into the source use the following workflow:

1. Checkout the source branch
2. Ensure your source branch contains the most updated code from the remote repo
3. Merge your feature branch into the source branch
4. Push the newly merged source branch back to the remote repo

The git commands for this workflow looks like this:

# Checkout the source branch that you want to merge your branch into (assuming your source was 'master')
git checkout master
# Ensure your source branch is up-to-date
git pull origin master
# Merge your feature branch INTO the source branch
git merge <feature branch>

# At this point, you might need to resolve merge conflicts

# Push your changes to the remote repo
git push origin master

Commands

Basic Commands

In the above workflow examples we saw some of the basic commands that you will use in your development workflow. In this section we will explore some of these commands in more detail.

ADD

# This command adds untracked or modified files to be committed. If you do not add changed files to your commit then git will not track that file and save its changes.
git add <file1> <file2> ....

RESET

# Reset has a number of different uses and is incredibly versatile.
# If you accidentally add a file to be committed and have not used the 'git commit' command you can remove it from the commit using this command
git reset HEAD <file1> <file2> ...

# If you would like to revert to a previous commit, but save all the work you may use this command:
git log

# Choose the proper git hash to revert to
git reset --soft <git hash>

# The following command is EXTREMELY powerful, and you should only use it if you are sure about what you are doing.
# If you would like to revert to a previous commit, but LOSE all your work you may use this command:
git log

# Choose the proper git hash
git reset --hard <git hash>

COMMIT

# Committing your work is essential to saving your work and is the heart of git
# First add all files you would like to add to your commit using the 'git add' command listed above

# Using the '-m' option will allow you to enter the commit message in a single command
git commit -m "<commit message>"

# Using the commit command without any operators will allow you to enter a much more detailed commit message through the vim editor
git commit

When using the 'vim' editor there are some basic things you will need to know about.

  • There is a 'command' mode and an 'insert' mode
    • Command mode is where you can use commands such as save and exit or search text
    • Insert mode allows you to do text editing
  • Vim always starts in command mode
    • To enter insert mode press the 'i' button on your keyboard
    • Enter your commit message
  • To exit you must return to command mode by pressing the 'ESCAPE' button
    • To exit you may use the following commands:
      •  :q - Exit without saving if no changes were made
      •  :q! - Exit without saving even if changes were made
      •  :x - Save and exit

A good resource on how to use VIM

PUSH

# After creating your commit you will want to 'push' your changes to the remote server. 
# If you do not push your changes then they will not be saved to the server and any data loss will result in loss of work.
git push origin HEAD

FETCH

# Your local repo will not know about commits or branches that happen on the remote server until you update your local machine
git fetch

MERGE

# You can merge a target branch into a source branch to bring in all of the code into your source branch
# Checkout the branch you want to merge code INTO
git checkout <branch name>

# Ensure that your branch is up-to-date
git pull

# Pull the code from the target branch into your current branch
git merge <target branch name>

PULL

# Pull can be a good way to update your current local branch to where the remote branch is.
# For example if you had checked out the master branch some time ago, but others have pushed new commits to the
# remote branch you will need to update your local branch.

# The pull command is actually a combination of the two commands above 'fetch' and 'merge'
# It will fetch first to obtain information on all of the new remote changes then merge those changes
# into your local copy
git pull

CHECKOUT

# The checkout command allows you to switch to a different branch as well as create new branches.

# To switch to a different branch you may do the following:
git checkout <branch name>

# If the branch does not exist in your local repo you will need to run the 'git fetch'
# command in order to switch to it.

# If the branch does not exist AT ALL you may create a new branch using the following command:
git checkout -b <new branch name>

STATUS

# The status command will provide you with the current status of your branch. It provides information
# such as files changed or whether or not you are up-to-date with the remote branch.
git status

DIFF

# Diff allows you to compare your current workspace with a different git hash. If you have made any
# changes to your tracked files then git will show you exactly what has changed.

# To show the diff between your working copy and the most recent committed git hash you may use this:
git diff

# If you would like to compare your working copy with a different git hash you may use:
git diff <git hash>

Advanced Commands

REBASE

# Rebasing is an EXTREMELY powerful tool which essentially rewrites history. Rebase will allow you to squash commits
# together and even change the source branch which you originally branched off from.

# When using rebase you can squash any number of commits so you must be careful with how many commits you are squashing.
# First use 'git log' to see what commits you would like to squash
git log

# Say you want to squash two commits. You may use
git rebase -i HEAD~2

# In the vim editor that pops up you may choose different options for each commit.
# Remember that the commits will be applied in order from the top down.

# It is possible to change your branch's source branch using this command.
# If you would like to place all of your branch's commits on top of the latest source branch you can do something like this:

# Checkout the source branch (assume source is 'master')
git checkout master

# Update your source branch
git pull origin master

# Return to your feature branch (the dash means return to previously checked out branch)
git checkout -

# Rebase onto the newly updated source branch
git rebase -i master

FORCE PUSH

# After rebasing you will need to push your changes to the remote repo. Normally git will see that your history no longer
# matches with that of the server's. It will then prevent you from pushing. It is possible to get around this through the
# use of 'force pushing'

# You must be VERY careful when force pushing since you are rewriting history for EVERYONE. If anyone has a local copy of
# the branch you are force pushing to, they will run into issues if they try to push their own version of the branch to 
# the server.

git push -f origin HEAD


CHERRY-PICKING

# Cherry-picking allows you to hand pick certain commits to add onto the top of your branch
git cherry-pick <git hash>

Merge Conflicts

When working in a team it will be inevitable that the same file will be touched by multiple developers. If multiple make changes in the same part of the file then it will result in a merge conflict when attempting to merge the files together. These conflicts can be resolved in your IDE directly or in any text editor.

More Information

Remember this page only provides a brief overview of the most basic commands. Git is extremely powerful and every command has multiple options. Please reference the links below to learn about other actions you can take in git.

Git tutorial

Offical Git documentation