• Documentation:
  • git manual: https://git-scm.com/doc
  • Tutorial by github: https://guides.github.com/activities/hello-world/
  • Got 15 minutes and want to learn Git? Interactive tutorial: https://try.github.io/levels/1/challenges/1
• Relevant Wiki pages:
  • Source Code has graphical examples and short stories to help you understand the flow of working with repos and submodules.
  • Git Workflow Best Practices (Dephy only, no public access)
  • Using Jira at Dephy (Dephy only, no public access)
  • Before pushing code, make sure it follows the Dephy C/C++ Programming Style Guide
• Tools:
  • When you install git you'll get git bash. All the examples below use it. Make sure to read the Configuration section.
  • If you prefer a graphical user interface you can request a GitKraken license.
  • To compare branches: WinMerge
  • Important: review the Two-Factor authentication section if you have log-in issues.
• Essential commands
• Additional commands & tricks
• GitHub.com tips and tricks
• Real life examples - Dephy specific
  • Cloning a repository and its submodule(s)
  • Switching Branch (Existing Branch)
  • Switching Branch (New Branch)
  • Committing work done on a detached head
• Configuration

• clone
• checkout
• pull
• push
• add and commit
• gitk

Use this to get code from the server.

Simplest case: clone a repository (no submodules, master branch)

git clone https://github.com/DephyInc/mySimpleRepo.git

Clone a repository that has submodules (master branch)

git clone --recursive https://github.com/DephyInc/myTypicalRepo.git

Clone a repository that has submodules, specific branch

git clone -b mySpecificBranch --recursive https://github.com/DephyInc/myTypicalRepo.git

For more examples, including real repositories: Cloning a repository and its submodule(s).

Use this to change/create branches

Change branch (when that branch already exists)

git checkout thatOtherBranch

Create a new branch and start using it (locally)

git checkout -b myNewBranch

Important: name your branches according to Dephy's git/Jira convention!

To send that new branch info to the server follow the previous command with:

git push --set-upstream origin myNewBranch

Tip: if you try git push without doing this first it will give you the exact command you need to use.

Use this to get a local copy of what's on the server

Want to get your colleague's latest work?

git pull

• Note 1: always pull before pushing
• Note 2: if you made changes and the server copy is different a merge will be triggered

Use this to upload your local copy to the server.

After you committed code, use this to send it up

git push

Note 1: always pull before pushing

Use add to stage (git's term for “prepare for a commit”) a file, and commit to commit all your staged files. Add can be called explicitly, or as part of commit.

Stage one specific file

git add thisOneFile.c

Stage all the modified files

git add -u

Commit your work after it was manually staged:

git commit -m "This is your commit message"

Stage all your modified files (equivalent to git add -u), then commit them with a message:

git commit -am "This is your commit message"

Use this to visualize and search local branches and commits.

This is how to open the built in visualization tool

gitk

• git merge
• git stash
• git log
• Everything else

Use this to merge two branches together. In this example we are on branch myBranch and we want to merge it with branch theirBranch.

git merge theirBranch

Tip: depending on the tree structure between the branch you may have to call git merge origin/theirBranch for it to be recognized.

If you are playing in Easy mode, the two branches will easily merge and you won't have anything to do. In Real Life mode conflicts are frequent. git will list the files that it wasn't able to merge automatically. You need to open them one after the other and look for the ««« and »»»> symbols, and manually fix what's wrong. Typical reasons why it won't automatically merge:

• Tabs (good) vs spaces (bad)
• Two people modified the same function
• Variable or function name changes

Once you are done fixing the conflicts (aka file doesn't have «< and »> anymore, and code makes sense) you need to tell git.

git add happyConflictFreeFile.c

Is that merge more complicated than what you can handle? There is a way to get out of it.

git merge --abort

Use this to discard (technically, save for later…) local changes.

Often you'll try something, then realize you can simply pull a new version that already includes those changes.

git stash

Tip: you can stash and pop multiple levels. 99% of the time I only stash as a way of “unlocking” my copy so I can pull new stuff.

Use this to get a list of the commits done in that branch

This will give you hash codes, commit messages, dates, etc.

git log

New git users can sometimes be surprised by a merge even though they did not type the git merge command. What triggers a merge? If two developers are working on the same branch git needs to unify the two versions of the source file. This can happen when you pull from the server.

You are developer A and you work with developer B. Monday morning you both pull the latest copy of the dev branch. Your local copy of source.c is exactly the same as the server's copy. This is what you both have:

#include "source.h"
int myVariable = 100;

Later that day you change myVariable to be 200. You do not commit or push this code, it only exists on your local machine. Your colleague B also thinks that myVariable shouldn't be 100. He changes it to 250, commits his code and pushes it. Tuesday you remember that you forgot to commit this important change. You do:

• git commit -am “Bug fix, variable had wrong value”
• git pull… and boom, you initiated a merge!

The reason is simple. On the server int myVariable = 250; and on your local machine int myVariable = 200;. Git doesn't know what's right, you have to decide.

• Open the file in your favorite editor
• Look for the »> symbols indicating a conflict.
• Fix the conflict, remove the indicators.
• Call git add source.c to let git know that you have fixed the conflict
• git commit -am “Fixed merged conflict, correct value is 200.”

The easiest way to prevent a merge conflict is to push and and pull frequently. Merging a few hours of work is usually far easier than merging days worth of work.

• To see what changed in a file:

  git diff

• After resolving a conflict, git add fileName where fileName is the file that was conflicted.

  git add fileName

• To list all of your branches, both on the server and locally:

  git branch -a

• To delete a remote branch:

  git push origin --delete branchName

• To populate a submodule that exists on the server, but that's empty on your computer:

  git submodule update --init

Dephy's GitHub page

If you click on Insights then on Network you can visualize the repo tree. This is useful if you are using the command line yet want to get a better understanding of the different branches.

We often need to refer to a vary specific line or section of the code. On github.com, if you click on the line number, it will highlight that line, and modify the URL for you. Here's an example where I'm pointing at main(), in main.cpp of the DSEP-64_PyVersion branch of the Actuator-Package repository: https://github.com/DephyInc/Actuator-Package/blob/DSEP-64_PyVersion/C/main.cpp#L46

Some/most of this is already covered in Source Code, but I'm including here for your convenience.

Latest version of a branch:

git clone --recursive -b branchName https://github.com/DephyInc/RepositoryName.git

Example:

git clone --recursive -b dev https://github.com/DephyInc/fx-rigid-mn.git

Specific commit:

git clone --recursive repoAddress/repoName.git
cd repoName
git checkout hash
git submodule update --recursive

Example:

git clone --recursive https://github.com/DephyInc/fx-rigid-mn.git
cd fx-rigid-mn
git checkout e922c5dd0464679cb43cfef4f56fff87e33e3b75
git submodule update --recursive

Source Code has detailed examples, including a very detailed description of the process of cloning a repository and its submodule(s)

In this example you have already cloned a repository to your computer. Let's say you are on the “develop” branch. You now need to run a test on a branch named “newFeatureBranch”.

First, if you have been modifying the sources you have two options:

• If you do not want to keep those changes discard them with the git stash command.
• If you want to save this work:
  1. Commit it git commit -am “This is my commit message”
  2. git pull to get the last version from the server. This may trigger a merge, but for now we will assume that git returned Already up to date.
  3. git push

You are now ready to change branch.

1. git pull will fetch the latest information from the server
2. git checkout newFeatureBranch will select that branch

You are now ready to run your test(s).

In this example you have already cloned a repository to your computer. Let's say you are on the “develop” branch. You now need to program a new feature. The work will go to a new branch named “newFeatureBranch”.

First, if you have been modifying the sources you have two options:

• If you do not want to keep those changes discard them with the git stash command.
• If you want to save this work:
  1. Commit it git commit -am “This is my commit message”
  2. git pull to get the last version from the server. This may trigger a merge, but for now we will assume that git returned Already up to date.
  3. git push

You are now ready to change branch.

1. git pull will fetch the latest information from the server
2. git checkout -b newFeatureBranch will create that new branch. The only difference between creating a new branch and switching to an existing branch is the -b command.
3. git push –set-upstream origin newFeatureBranch will send the information about this new branch to the server.

You are now ready to do your work. Once you are done it's a simple matter of committing, pulling and pushing.

git commit -m "Your commit message"
git branch temporaryBranch
git checkout branchYouWantToCommitTo
git merge temporaryBranch

Download git from https://git-scm.com/download/ and follow the instructions.

After installing git, all you need to do is:

1. Set your git username/email to make sure that your commits are associated with your name
2. Set your github.com password
3. git config –global core.autocrlf input so git use LF as end of line (that makes Bash scripts work equally well on Win and Unix)

Since we have started using 2 factor authentication, you may have to use personal access tokens when attempting to access the github repositories from the command line and certain applications. Simply substitute your password for the token. To get a token, go to github.com. Then got to settings→Developer Tools→ Personal Access Tokens.