Git
How to use git with the papaprazzi master repo.
The RepositoryStructure page explains the various branches. Most users probably want the stable v4.2 branch. The master branch is for active development.
Contents
Git help and resources
There are tons of tutorials, etc. out there... first check out the git documentation.
You can also get help on any Git command by doing git command -h or git help command.
Never used git before? Read (and watch) learn.github.com/p/intro.html.
To get an understanding off the git internals the video Getting Git is excellent.
More:
- git screencasts
- git help from github
- Git crash course for SVN users
- git ready - short tips
- nice Git reference
- more Git cheat sheets
Before You Start
Git is not an evolution of SVN (like SVN is from CVS). This may lead to a lot of extra headscratching among migrates. You have been warned.
Basic Git configuration
First tell git your real name and your e-mail address. You should add these before you start using Git:
git config --global user.name "Your Name" git config --global user.email you@yourdomain.example.com
There is a nice guide of how to set up git for use with github.
Get the code
If you plan to contribute or just to push your own config to github please use Option 1 to create your own account and fork the papaprazzi repo.
Otherwise use Option 2 to directly get the code.
Option 1: Fork paparazzi to your own github repo and clone from there
Set up a Github account
If you want some github awesomeness you have to create an account there and set up git. Do not forget to provide your ssh key and github token, otherwise you will not be able to access your repositories.
Fork paparazzi and clone your new repo
To fork paparazzi, just log in to github, go to the main papaprazzi software repository and click fork at the top of the page. This created the new paparazzi repository on your own github account which you can now clone to your local machine.
When you initially clone a repo to your local machine git gives this remote repo the name origin.
git clone git@github.com:<your github username>/paparazzi.git
Optionally you can give your remote a more descriptive name when cloning by adding the option -o:
git clone -o <username> git@github.com:<your github username>/paparazzi.git
The option -o <name> uses name to keep track of the repository instead of using the remote name origin. You can name the remote for your own paparazzi fork according you your username and the paparazzi master repo upstream (or paparazzi) to avoid confusion.
Adding remotes
Now you want to add the main repo as a remote with the name upstream (or paparazzi) to easily pull changes from there:
git remote add upstream git://github.com/paparazzi/paparazzi.git
The above URL provides read-only access, if you are a dev and have write access to the main repo as well you want to use:
git remote add upstream git@github.com:paparazzi/paparazzi.git
Option 2: Directly clone paparazzi without a github account
Clone directly from the master repo (read-only):
git clone git://github.com/paparazzi/paparazzi.git
or if you are behind a firewall with an http proxy available:
git clone https://github.com/paparazzi/paparazzi.git
This will name the remote Paparazzi repository origin. You can add the option -o name to use name (e.g. upstream or paparazzi) to keep track of the paparazzi master repo to avoid confusion.
git clone -o upstream git://github.com/paparazzi/paparazzi.git
Basic git usage
See what's going on
To show the status (modified and staged changes) you can run
git status
To list your branches and the corresponding upstream branch (the one marked with the star is the currently used branch):
git branch -vv
Gitk is your friend if you want to visualize all remotes/branches and history:
gitk --all
Updating from the main repository (pull)
Have a look at the very good short overview of pushing and pulling on gitready.com.
To fetch the changes from the stable branch (e.g. currently v4.0) on github and merge them into your local branch run
git pull <remote> v4.0
Where <remote> is the name for the remote to the main Paparazzi repo and is usually upstream or origin depending on your earlier setup.
If you want to use the latest bleeding edge version, checkout out the master (development) branch:
git checkout master
To update it:
git pull upstream master
Publishing your changes
To push your (already locally committed) changes to your own github master branch
git push <remote> <branch>
Where <remote> is the name for the remote to your own github repo and is your username if you named it like explained above. <branch> is the branch you want to push to your remote repository, either master or your topic branch.
Contribute
If you are working on a new feature, you should do all your work in a topic branch which then can be merged back into master when it is ready. If you are just working on a small fix for a specific release, you can do that from the branch for the respective version. Please send us a pull request on github.
I you want to update your branch it is good practice (in most cases) to use git up (git pull --rebase) instead of git pull (See below to define git up as an alias for git pull --rebase). This will rebase your changes ontop of the current master instead of merging. It is very useful to keep the history more readable and make bug searching easier.
So the basic pattern looks something like this:
- Fetch the latest versions from the main repo: git fetch or git remote update to update all remotes
- Create a new branch of the current master branch:
git checkout -b new_feature upstream/master - Add commit changes to the new branch
- Rebase updates from upstream branch:
git up upstream/master - Push it to the repo when it is ready
- send us a pull request
Advanced Configuration and helpful tools
If you want to inspect your global configuration, have a look at the .gitconfig file in your home directory.
The per repository configuration is stored in the .git/config file in your repository.
Colors and Aliases
You also might want to set some color options and aliases, e.g.:
git config --global color.ui auto # colors for all git config --global alias.st status # make `git st` work git config --global alias.co checkout # make `git co` work git config --global alias.ci commit # make `git ci` work git config --global alias.br branch # make `git br` work git config --global alias.up "pull --rebase" # make `git up` work similar to svn up git config --global alias.lg "log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --date=relative"
Line endings
Although you might think you’re immune to CRLF-ended files on mac and linux, you are not. It is possible to download files from an external source that use CRLF, and thus commit them into your repo. You should globally set your config to convert line endings on commit so they are always LF in the repo (or omit the --global for paparazzi only):
git config --global core.autocrlf input
If you are on a windows box by any chance set:
git config --global core.autocrlf true
Magit
If you are an emacs user you might want to have a look at http://philjackson.github.com/magit/
git status in shell
For bash: http://www.gitready.com/advanced/2009/01/23/bash-git-status.html
For zsh: http://www.wunjo.org/zsh-git/
