Version control

Git and GitHub

Git is a distributed version control system. With Git, every developer has the full history of the code repo locally. Github is an Internet host for git repos. Similar hosts include Gitlab, Bitbucket, Gitbucket; and there are many more.

As we transition to fully open-source programming, with the source mainly consisting of text files, git and github becomes critically important.

We suggest that all the source files should be tracked using git and collaborated via github.

Before publication, a git repo can be set as private.

Manage local repo

  1. Initiate
cd /somedir   # navigate to the directory that you want to create the repo
git init      # Initiate the git repo

This creates a new subdirectory named .git that contains all of your necessary repository files — a Git repository skeleton.

  1. Starting tracking files or Staging modified files
git add somefile  # start tracking some files

# or

git add --all     # start tracking all files in the directory
  1. Commit
git commit -m "Initial commit"      # commit the changes with a message

# or

git commit -a -m "Initial commit"   # auto commit skipping the staging area
Tip

Always include a message when committing. A suggested format is “verb” + “subject”

  1. Ignore
cat .gitignore
*.err       # ignore all the logs on errors
build/      # ignore the build directory

You can edit the .gitignore file at anytime.

  1. Status and History

You can check the git status using,

git status      # Shows you the current git status 
git log         # Shows you the git history
  1. Removing files
git rm Makefile

This removes the Makefile from Git but not from the directory.

  1. Undo
git commit --amend              # amend the current change to the previous commit
git restore --staged README.md  # unstage a staged file
git restore READE.md            # discard changes in working directory.

Manage remote repos

  1. Git clone
git clone https://github.com/JulianTao/chgpu_agave_template

This will clone the github repo JulianTao/chgpu_agave_template to your local machine.

The local repo will have the same name as the remote, but can be modified later.

  1. Check remotes
git remote

This will show which remote servers you have configured.

If you run git remote in side the local repo, you see that a default git name origin is assigned to the remote repo.

Now if you run git remote get-url origin, you will see the url associated with this remote repo.

Alternatively, run git remote -v, you see the urls for fetching and pushing actions.

  1. Add remote repos
git remote add <shortname> <url>

This will add a new remote explicitly with the specified shortname and url. The shortname can be used latter in lieu of the whole URL, for example git fetch shortname. This is useful when collaborating.

If you need to change the url of a remote, you can use,

git remote set-url <url>
  1. Fetching and Pulling from the remotes
git fetch <remote>

This command will pulls down all the data from the remote project that you don’t have yet. You can then merge in any branches from that remote.

Alternatively, if your current branch is set up to track a remote branch, you can use git pull to automatically fetch and then merge that remote branch into your current branch.

  1. Pushing from local branch to remotes
git push <remote> <branch>

With this command, you can share your local branch by pushing it to the remote. You need to specify the remote and branch that you want to push to. You also need to have the write access to the remote.

  1. Renaming and Removing remotes
git remote rename <oldname> <newname>       # rename a remote from <oldname> to <newname>
git remote remove <shortname>               # remote the remote <shorname>

Collaborate using Github

  1. Adding an existing project to GitHub using the command line

    Many times, we already started working on a project on our computer, but it is not on GitHub. If you use command line tools, there are two ways to add your local directory to Github.

    A detailed instruction is on GitHub

2 General workflow

  • There are many git workflows. To start, let’s use the simple Github Workflow.

Configure your local git to simplify the workflow

git clone https://github.com/username/repo.git
Username: your_username
Password: your_token
git config --global credential.helper store
git config --global branch.autosetuprebase always

Further reading

Atlassian. n.d. “Learn Git- Git Tutorials, Workflows and Commands | Atlassian Git Tutorial.” Atlassian. https://www.atlassian.com/git.
“Git - Book.” n.d. https://git-scm.com/book/en/v2.
“Git - the Simple Guide - No Deep Shit!” n.d. https://rogerdudler.github.io/git-guide/.
“Git Handbook \(\cdot\) GitHub Guides.” n.d. https://guides.github.com/introduction/git-handbook/.
“Learn Git with Bitbucket Cloud | Atlassian Git Tutorial.” n.d. https://www.atlassian.com/git/tutorials/learn-git-with-bitbucket-cloud.