Difference between revisions of "Git"

From PaparazziUAV
Jump to: navigation, search
(Line endings)
(updated, hopefully makes it a bit more clear)
Line 19: Line 19:
  
 
== Before You Start ==
 
== 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 migraters. You have been warned.
+
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 ===
 
=== Basic Git configuration ===
Line 27: Line 27:
 
  git config --global user.email ''you@yourdomain.example.com''
 
  git config --global user.email ''you@yourdomain.example.com''
  
=== Set up a Github account ===
+
== Get the code ==
If you want some [http://github.com/ github] awesomeness you have to set up an account there and set your [http://help.github.com/git-email-settings/ github token]. Just go to the webpage and create an account there. Do not forget to upload your ssh key there. [http://github.com/guides/providing-your-ssh-key Here] is a good tutorial on providing your '''ssh key''' to GitHub. Otherwise you will not be able to access your repositories.
+
'''If you plan to contribute or just to push your own config to [http://github.com/ github] please use Option 1 to create your own account and fork the [http://github.com/paparazzi/paparazzi/ papaprazzi repo]'''.
  
== Get the code ==
+
Otherwise use Option 2 to directly get the code.
If you plan to contribute or just to push your own config to github '''please first [http://help.github.com/forking/ fork] the [http://github.com/paparazzi/paparazzi/ papaprazzi repo] on github'''.
+
 
Just log in and click fork at the top of the main paparazzi software repository.
+
 
 +
=== Option 1: Fork paparazzi to your own github repo and clone from there ===
 +
 
 +
==== Set up a Github account ====
 +
If you want some [http://github.com/ github] awesomeness you have to set up an account there and set your [http://help.github.com/git-email-settings/ github token].
 +
Do not forget to [http://github.com/guides/providing-your-ssh-key provide your ssh key], otherwise you will not be able to access your repositories.
  
=== Option 1: clone from your own github repo ===
+
==== Fork paparazzi and clone your new repo ====
If you already [http://help.github.com/forking/ forked] the paparazzi-software repo to your own github account:
+
To [http://help.github.com/forking/ fork] paparazzi, just log in to github, go to the [http://github.com/paparazzi/paparazzi/ 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 [http://help.github.com/remotes/ remote] repo the name ''origin''.
 +
git clone git@github.com:<your github username>/paparazzi.git
 +
You can give your remote a more descriptive name:
 
  git clone -o <username> git@github.com:<your github username>/paparazzi.git
 
  git clone -o <username> git@github.com:<your github username>/paparazzi.git
  
The option ''-o <name>'' uses ''name'' to keep track of the upstream repository instead of using the remote name ''origin''. It is recommended to call the remote for the papaprazzi master repo ''paparazzi'' and name your own github remote according to your name to avoid confusion.
+
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 ====
 
==== Adding remotes ====
Now you want to add the main repo as a remote with the name ''paparazzi'' to easily pull changes from there:
+
Now you want to add the main repo as a remote with the name ''upstream'' (or ''paparazzi'') to easily pull changes from there:
cd paparazzi
+
  git remote add upstream git://github.com/paparazzi/paparazzi.git
  git remote add paparazzi 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:
 
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 paparazzi git@github.com:paparazzi/paparazzi.git
+
  git remote add upstream git@github.com:paparazzi/paparazzi.git
  
=== Option 2: clone from github without an account ===
+
=== Option 2: Directly clone paparazzi without a github account ===
Otherwise clone directly from the [http://github.com/paparazzi/paparazzi/ master repo] (read-only):
+
Clone directly from the [http://github.com/paparazzi/paparazzi/ master repo] (read-only):
 
  git clone git://github.com/paparazzi/paparazzi.git
 
  git clone git://github.com/paparazzi/paparazzi.git
 
or if you are behind a firewall with an http proxy available:
 
or if you are behind a firewall with an http proxy available:
 
  git clone https://github.com/paparazzi/paparazzi.git
 
  git clone https://github.com/paparazzi/paparazzi.git
  
== Get to work ==
+
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
 
To show the status (modified and staged changes) you can run
 
  git status
 
  git status
Line 59: Line 71:
 
  gitk --all
 
  gitk --all
  
=== Pull and push ===
+
=== General push and pull ===
 
Have a look at the very good short overview of [http://gitready.com/beginner/2009/01/21/pushing-and-pulling.html pushing and pulling on gitready.com].
 
Have a look at the very good short overview of [http://gitready.com/beginner/2009/01/21/pushing-and-pulling.html pushing and pulling on gitready.com].
  
To fetch the changes from the paparazzi master branch on github and merge them into your local branch run
+
To fetch the changes from the main paparazzi master branch on github and merge them into your local branch run
 
  git pull <remote> master
 
  git pull <remote> master
Where <remote> is the name for the remote to the main paparazzi repo and is usually ''paparazzi'' or ''origin''.
+
Where <remote> is the name for the remote to the main paparazzi repo and is usually ''upstream'', ''paparazzi'' or ''origin''.
  
 
To push your (already locally committed) changes to your own github master branch
 
To push your (already locally committed) changes to your own github master branch
  git push <remote> master
+
  git push <remote> <branch>
Where <remote> is the name for the remote to your own github repo and is <username> if you named it like explained above.
+
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 ===
+
== Contribute ==
It is advisable to do all your work in a branch an then merge back into master when it is ready.
+
'''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 (or the dev branch) when it is ready.
 +
If you are just working on a small fix, you can do that from the master branch.
 
Please send us a [http://help.github.com/pull-requests/ pull request] on github.
 
Please send us a [http://help.github.com/pull-requests/ 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 [http://learn.github.com/p/rebasing.html 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:
 +
#Create a new branch of the current ''master'' (or ''dev'') branch:<br>git checkout -b new_feature upstream/master
 +
#Add commit changes to the new branch
 +
#Rebase updates from upstream branch:<br>git up upstream/master
 +
#Push it to the repo when it is ready
 +
#send us a [http://help.github.com/pull-requests/ pull request]
  
 
== Advanced Configuration and helpful tools ==
 
== Advanced Configuration and helpful tools ==

Revision as of 09:01, 19 June 2011

How to use git with the papaprazzi master repo.

Git help and resources

There are tons of tutorials, etc. out there... You can also get help on any Git command by doing git command -h or git help command.

For a quick introduction see the Git crash course for SVN users. For git newbies the Git CheatSheet is also nice.

To get an understanding off the git internals the video Getting Git is excellent.

More:

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

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 set up an account there and set your github token. Do not forget to provide your ssh key, 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

You can give your remote a more descriptive name:

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

Gitk is your friend if you want to visualize all remotes/branches and history:

gitk --all

General push and pull

Have a look at the very good short overview of pushing and pulling on gitready.com.

To fetch the changes from the main paparazzi master branch on github and merge them into your local branch run

git pull <remote> master

Where <remote> is the name for the remote to the main paparazzi repo and is usually upstream, paparazzi or origin.

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 (or the dev branch) when it is ready. If you are just working on a small fix, you can do that from the master branch. 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:

  1. Create a new branch of the current master (or dev) branch:
    git checkout -b new_feature upstream/master
  2. Add commit changes to the new branch
  3. Rebase updates from upstream branch:
    git up upstream/master
  4. Push it to the repo when it is ready
  5. 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

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/