Git Help
This page is dedicated to documented the project's preferred git strategy as well as provide some quick information about git for those less familiar with it on this project.
The project will be divided into a "master" and "develop" branch. Features will branch off the "develop" branch. Master will only get commits from develop, or from "release" branches (that branch from develop).
This branch holds only stable releases for the project. All builds sent out to be played will be marked on the master branch with tags for their version number.
This branch will hold commits of completed features. All developers should pull and work from this branch. The develop branch should generally never be directly worked on. All developers are expected to branch from develop into their own feature branches and merge back onto develop (with the --no-ff flag set).
All features will be developed in feature branches that will branch off the develop branch. You as a develop generally have complete autonomy with your feature branch while developing. This includes making remote feature branches for other developers to work with you on your feature. It is extremely recommend that when you merge back onto develop that you rebase to clean up your commits, though.
We will generally have a "release" branch when we want to push out a new master commit. For this, we'll make a new branch for the version off of develop. Developers and testers will test on this branch and make any hotfixes as necessary to just this release. Once complete, it will be merge into "master". The reason for this is that when we have a release candidate, we don't want more features (that are being pushed into "develop" to get mixed in during the release testing). Once it is merged into develop, if any changes were added, it will also be merged into "develop" just like a feature branch.
In the rare time we want to fix a major bug with a release candidate on "master", we can make a hotfix branch off of master and merge that back into master and develop once fixed. These branches should be kept to an absolute minimum though.
Here is a picture that more or less demonstrates how this system looks:
I've taken the liberty to try and teach a little bit of git as it will relate to this project. I highly recommend you look up some better git tutorials, though.
git checkout develop // Make sure you are on the develop branch.
git checkout -b my_feature_name // Make a new feature branch and name it
// You are now free to develop as necessary
git checkout develop // Go back to the develop branch
git pull origin develop // Make sure develop is in its latest stages.
git merge --no-ff my_feature_name // Merge in your changes. The --no-ff flag is important for maintaining history. If you do not have the flag, your commits may just be merged in as if you had done them on develop itself (which is generally frowned upon for this project)
// Fix any merge conflicts as necessary
Make some changes to some files. When you have a good stopping point, you should commit them. To commit files, you first need to add them to the "stage". Only files added to the stage will be saved in the commit. Any unstaged file changes will be ignored.
git add path/to/my_file.txt // Adds a file to the stage
git add -A // Adds ALL changes to the stage (be sure to double check when you do this!!!)
git commit -m 'My commit message' // Commits the changes and adds a nice label in.
You should commit often. Don't worry about making all of your commits legible to other people as long as it helps you out while you are developing. It's your feature branch. But, remember that you will need to clean up a bit when you submit your code back to the repo.
Remember: Your commits are just locally saved changes on your computer. They are not saved on the remote server. No one can see your commits or changes until you push them (or they are pulled).
While there are no restrictions for your local commits, when you push them, it is nice to have them organized for the project. Imagine the following list of commits on your local feature branch: `
- 69517ec 2015-09-24 Started important feature
- d1256c8 2015-09-23 changes to important feature
- ee42128 2015-09-22 more changes
- d63616e 2015-09-22 haha omg so many changes
- 88bb1c8 2015-09-22 I hate my life
- 88bb1c8 2015-09-22 Feature done! `
Those may have been useful while developing, but other developers don't need to see this. So, before we go merging these back into develop, let's fix them up:
git rebase -i develop // Note that 'develop' here is assumed to be the commit you branched from. If it isn't, use the reference or hash (like the 69517ec above) that is at the commit you branched from, NOT your first commit
This will open up an editor allowing you to edit your commits. In this case, we would like to squash all of our commits together (read the page that opens or read up on your GUI tool for how to rebase commits together).
Now we can be left with a single commit: `
- f0aa505 2015-09-24 Added important feature `
Now you can move on to merge that into develop.
git status // shows a list of all of the changed files for the current commit you are working on as well as which are staged and which are not
git diff --color // Shows the changes you made to each file
git reset // Moves all staged files (files added using git add) back to unstaged
git reset --hard // Deletes all changes to files (includes both staged and unstaged files). Be careful! This can not be undone!
git reset --soft HEAD^ // "Undos" the last commit, moving all of the changes in that commit to your stage.(Please do not use this on pushed commits!)
git stash // Moves all of your changes to a temporary commit and clears your changes. (Useful for when you need to switch to a different branch)
git stash pop // Retrieves all of the changes that were stored away in git stash
git log // See a list of commits in history [not super useful]
git log --graph --full-history --all --color --date=short --pretty=format:"%x1b[31m%h%x09%x1b[32m%d%x1b[0m%x20%ad %s" // See a nicely formatted list of git commits and the history
Some useful aliases (this works for bash). Add to your ~/.bashrc file
alias gitpulloverwrite='git pull -s recursive -X theirs origin r'
alias gs='git status'
alias gd='git diff --color'
alias gc='git commit'
alias ga='git add'
alias gaa='git add -A'
alias gb='git branch'
alias gk='git checkout'
alias gkm='git checkout master'
alias gpo='git push origin'
alias gpom='git push origin master'
alias gg='git log --graph --oneline --all'
alias gl='git log --graph --full-history --all --color --date=short --pretty=format:"%x1b[31m%h%x09%x1b[32m%d%x1b[0m%x20%ad %s"'
alias gll="git log -p -40 | vim - -R -c 'set foldmethod=syntax'"
alias gundo='git reset --soft HEAD^'