Git 101 - StarEngine/engine GitHub Wiki
Index
Learn Git fast and good
Git is awesome, which is why we use it. It might be scary at the beginning, so if you would like a nice introduction on Git, feel free to try out this interactive tutorial by GitHub and Codeschool, which teaches you all the basics you need to get started.
Codeschool is a great place to learn stuff, and if you can afford a subscription, we highly recommend their Git real series, which goes quite advanced and will learn you most of what you will ever need to know about Git. The Pro Git book, which you can find for free here, is also a good read and will teach you all you ever need to know. With all this material, you should be more than comfortable enough to use git and contribute to the StarEngine.
In case you want to understand how Git works under the hood and get a deeper and an even more advanced knowledge of git, than we recommand reading A Hacker's Guide to Git. It's well written and relativly short.
Git Guidelines
Quick Tips:
- NEVER force a push
- NEVER rebase a published branch
- In general, the preferred workflow is:
- create a branch from master, check it out, do your work
- test and commit your changes
- when done with the feature, clean up your branch (squash, rebase, ... )
- checkout master, make sure it's up-to-date with upstream changes
- merge (rebase) your branch into master
- test again (and again)
- push your local copy of master up to the remote repository master (origin/master)
- make a pull request
- once the pull request has been accepted:
- delete your feature branch
- pull the newest master branch
Line endings
All text files in must be normalized so that lines terminate in the unix style (LF). Make sure to configure your code IDE to respect this rule. Please do not commit files that terminate in CRLF, these pull requests will be rejected!
Commit Messages
Commit messages should be brief and should not be much longer than 50 characters. Use the present tense when writing messages, i.e. "Fix bug, apply patch", not "Fixed bug, applied patch."
Submodules
StarEngine is awesome thanks to the help of many other opensource libraries. In order to keep them easily up-to-date and in order to not mangle them with our sourcecode we opt for git's submodules as our package manager. It's easy to setup and use and does exactly what we need, without the need for any other technology.
You can learn more information about Git submodules by clicking here. In short it means that everytime you do a git pull to get the latest starengine source you also have to do git submodule update.
This process is not the easiest and is certainly not the fasted one in git. Check out the submodule related aliases to be use submodules a little faster and less error prone.
Aliases to make your life easy
A visual representation of your history in the form of a graph:
git config --global alias.graph "log --graph --all --format=format:'%C(bold blue)%h%C(reset) %C(white)%s%C(reset) %C(bold white) - %an%C(reset) %C(bold yellow)%d%C(reset)- %C(bold cyan)%ai%C(reset)' --abbrev-commit"
A compact way to show your history in the form of a list, written by Fabrice Lété:
git config --global alias.qlog "log --date=short --pretty=format:\"%C(yellow)%h %Creset%ad %Cgreen%an %Creset%s\""
Automaticly update our submodules when you pull the latest sourcecode:
git config --global alias.pullall '!f(){ git pull "$@" && git submodule update --init --recursive; }; f'
Pull and Update a certain submodule:
git config --global alias.up-sub '!f() { cd $1 && git checkout master && git pull && git submodule update --init --recursive; }; f'
This way you could for example easily update only the SDL2 Library:
git up-sub libs/sdl2