Git

Git is a distributed version control system (VCS), designed to work well with highly non-linear workflows. It was initially conceived to support development of the Linux kernel, and has since become the most widely-used VCS for software development.

Git is used to maintain most of the software used by the group, including PHASTA, Chef, vtkpytools, and more. Learning git will allow you to make changes to these codes and share them with the group, in addition to allowing you to test proof-of-concept codes without fear of accidentally deleting code.

Learning Git

If you're not familiar with version control systems, see the What is Version Control? video for some motivation on why VCS is used.

Next, if you're completely new to git, the What is git? video from the maintainers of git is a great primer. If you prefer a written medium rather than a video, the Pro Git book would be a good place to start (specifically, sections 1.1 About Version Control and 1.3 What is Git?).

Once you've gotten a general idea on VCS and the core concepts of git, try out Learn Git Branching. It is a great interactive, visual training program that shows the basics. It'll help you learn the actual command line functions of git while the visuals help to give an understanding of what exactly those commands do. Even if you're not completely new to git, it may help you to understand some concepts you didn't before.

Refreshers

If you need a quick refresher on how to do certain actions, or just a quick cheat sheet this interactive cheatsheet is quite nice for figuring out what commands you need to move changes from one "stage" to another.

Commit Message Etiquette

When writing a commit, it's good practice to follow the basic guidance found in the git documentation for writing a commit message:

Though not required, it’s a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git.

So something like:

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Could also include
some bullet points:
 - Item 1
 - Item 2

Other general good ideas it to have the first word of the title be a verb (ie. "Fix...", "Add...", "Refactor...") and have them be present tense (mostly because it's generally less characters: Fix vs Fixed, Add vs Added, etc.). This blog post offers some other good advice on writing "good" commit messages.

Basic Git

Basic information to get started with Git can be found at http://rogerdudler.github.io/git-guide/.

Git repository (repo)

Is a directory that contains files of the current branch and a hidden .git directory

Contains an Index in .git that acts as a staging area for all your branches

Contains a HEAD in .git that points to the last commit you made

Your PHASTA repository should always be at ~/git-phasta/phasta

Create a new repository

git init

Checkout a repository

git clone /path/to/repo

git clone user@host:/path/to/repo

Add files to be tracked in the git index

git add <filename1> <filename2> ...

git add *

git add -u (all files updated since last commit)

Commit changes to HEAD

git commit -m "my_username: my comments about this commit"

Push changes to remote repo

git push origin master (pushes the master branch to the original/main repo)

Connect to a remote server

git remote add origin <server> (connects <server> to your main, or origin repository)

git remote add myrepo <server> (connects <server> to a named branch called mybranch)

Note: <server> could be user@host:/path/to/repo

Create and delete branch

git checkout -b branch_name (creates and checkout branch)

git checkout master (checkout master branch)

git branch -d branch_name (delete branch we just created)

Push branch to a remote

git push origin branch (pushes from your main origin repo)

Update and merge

git pull (so all branches are up-to-date for the merge)

git merge origin/master (merges current branch with origin's master branch)

If a merge has conflicts, you need to edit the conflict files provided by Git, and then mark them as merged with git add

Compare code in different branches

git diff <branch_a> <branch_b>

View history of commits

git log

git log --author=foo

git log --pretty=oneline (show each commit as one line)

git log --graph --oneline --decorate --all (ASCII tree of branches, commits, merges)

git log --name-status (show which files changed in each commit)

git log --help (more information)

Git Prompt Statement (PS1)

1. Acquire git-prompt.sh from https://github.com/git/git/blob/master/contrib/completion/git-prompt.sh, and save it somewhere like ~/.git-prompt.sh
2. Edit your ~/.bashrc to say source ~/.git-prompt.sh before the lines that set your PS1
3. Modify your PS1 string to include $(__git_ps1 "(%s)") where you want the current branch to appear in your prompt