guide/tutorials.git.md

   1 # Working With Git
   2
   3 Kohana uses [git](http://git-scm.com/) for version control and [github](http://github.com/kohana) for collaboration. This tutorial will show you how to use git and github to build a simple application.
   4
   5 ## Installing and setting up Git on your machine
   6
   7 ### Installing Git
   8
   9 - OSX: [Git-OSX](http://code.google.com/p/git-osx-installer/)
  10 - Windows: [Msygit](http://code.google.com/p/msysgit/)
  11 - Or download it from [git-site](http://git-scm.com/) and install it manually (see git website)
  12
  13 ### Basic global settings
  14
  15     git config --global user.name "Your Name"
  16     git config --global user.email "youremail@website.com"
  17
  18 ### Additional but preferable settings
  19
  20 To have a better visualisation of the git commandos and repositories in your command-line, you can set these:
  21
  22     git config --global color.diff auto
  23     git config --global color.status auto
  24     git config --global color.branch auto
  25
  26 ### Setting auto-completion
  27
  28 [!!] These lines are only to use on an OSX machine
  29
  30 These lines will do all the dirty work for you, so auto-completion can work for your git-environment
  31
  32     cd /tmp
  33     git clone git://git.kernel.org/pub/scm/git/git.git
  34     cd git
  35     git checkout v`git --version | awk '{print $3}'`
  36     cp contrib/completion/git-completion.bash ~/.git-completion.bash
  37     cd ~
  38     rm -rf /tmp/git
  39     echo -e "source ~/.git-completion.bash" >> ~/.bash_profile
  40
  41 ### Always use LF line endings
  42
  43 This is the convention that we make for Kohana. Please set this settings for your own good and especially if you want to contribute to the Kohana community.
  44
  45     git config --global core.autocrlf input
  46     git config --global core.safecrlf true
  47
  48 [!!] More information about line endings at [github](http://help.github.com/dealing-with-lineendings/)
  49
  50 ### More information to get you on the track
  51
  52 - [Git Screencasts](http://www.gitcasts.com/)
  53 - [Git Reference](http://gitref.org/)
  54 - [Pro Git book](http://progit.org/book/)
  55
  56 ## Initial Structure
  57
  58 [!!] This tutorial will assume that your web server is already set up, and you are going to create a new application at <http://localhost/gitorial/>.
  59
  60 Using your console, change to the empty directory `gitorial` and run `git init`. This will create the bare structure for a new git repository.
  61
  62 Next, we will create a [submodule](http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html) for the `system` directory. Go to <http://github.com/kohana/core> and copy the "Clone URL":
  63
  64 ![Github Clone URL](http://img.skitch.com/20091019-rud5mmqbf776jwua6hx9nm1n.png)
  65
  66 Now use the URL to create the submodule for `system`:
  67
  68     git submodule add git://github.com/kohana/core.git system
  69
  70 [!!] This will create a link to the current development version of the next stable release. The development version should almost always be safe to use, have the same API as the current stable download with bugfixes applied.
  71
  72 Now add whatever submodules you need. For example if you need the [Database] module:
  73
  74     git submodule add git://github.com/kohana/database.git modules/database
  75
  76 After submodules are added, they must be initialized:
  77
  78     git submodule init
  79
  80 Now that the submodules are added, you can commit them:
  81
  82     git commit -m 'Added initial submodules'
  83
  84 Next, create the application directory structure. This is the bare minimum required:
  85
  86     mkdir -p application/classes/{controller,model}
  87     mkdir -p application/{config,views}
  88     mkdir -m 0777 -p application/{cache,logs}
  89
  90 If you run `find application` you should see this:
  91
  92     application
  93     application/cache
  94     application/config
  95     application/classes
  96     application/classes/controller
  97     application/classes/model
  98     application/logs
  99     application/views
 100
 101 We don't want git to track log or cache files, so add a `.gitignore` file to each of the directories. This will ignore all non-hidden files:
 102
 103     echo '[^.]*' > application/{logs,cache}/.gitignore
 104
 105 [!!] Git ignores empty directories, so adding a `.gitignore` file also makes sure that git will track the directory, but not the files within it.
 106
 107 Now we need the `index.php` and `bootstrap.php` files:
 108
 109     wget http://github.com/kohana/kohana/raw/master/index.php
 110     wget http://github.com/kohana/kohana/raw/master/application/bootstrap.php -O application/bootstrap.php
 111
 112 Commit these changes too:
 113
 114     git add application
 115     git commit -m 'Added initial directory structure'
 116
 117 That's all there is to it. You now have an application that is using Git for versioning.
 118
 119 ## Updating Submodules
 120
 121 At some point you will probably also want to upgrade your submodules. To update all of your submodules to the latest `HEAD` version:
 122
 123     git submodule foreach 'git checkout master && git pull origin master'
 124
 125 To update a single submodule, for example, `system`:
 126
 127     cd system
 128     git checkout master
 129     git pull origin master
 130     cd ..
 131     git add system
 132     git commit -m 'Updated system to latest version'
 133
 134 If you want to update a single submodule to a specific commit:
 135
 136     cd modules/database
 137     git pull origin master
 138     git checkout fbfdea919028b951c23c3d99d2bc1f5bbeda0c0b
 139     cd ../..
 140     git add database
 141     git commit -m 'Updated database module'
 142
 143 Note that you can also check out the commit at a tagged official release point, for example:
 144
 145     git checkout 3.0.6
 146
 147 Simply run `git tag` without arguments to get a list of all tags.
 148
 149 All done!