||This is a draft !!!||

= Bcfg2 Git HOWTO =
This is a draft document in progress, and is not official policy of the Bcfg2 project.

== Git Resources ==
 * The [http://git-scm.com/ project page] of git provides documentation and more.
 * A [http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html git tutorial]
 * [http://git-scm.com/course/svn.html Git-SVN Crash Course] for 
 * [http://img705.imageshack.us/img705/2267/gitcheatsheet.png Git Cheat Sheet], [https://github.com/AlexZeitler/gitcheatsheet Git Cheat Sheet], [http://zrusin.blogspot.com/2007/09/git-cheat-sheet.html Git Cheat Sheet] , and [http://zrusin.blogspot.com/2007/09/git-cheat-sheet.html Git Cheat Sheet] 

== Repositories ==

 * [http://git.mcs.anl.gov/bcfg2.git/ git.mcs.anl.gov:bcfg2.git] is the main upstream repository
 * [https://github.com/solj/bcfg2 git://github.com/solj/bcfg2.git] is a [https://github.com/ github] mirror that people can use to send pull requests

== Configuration ==

After installing git, identify yourself to git with your name and your email address.
{{{
$ git config --global user.name "Your name"
$ git config --global user.email "your.name@example.com"
}}}

If you want to use a different email address for the Bcfg2 repository set it after the checkout in the repository directory with:

{{{
$ git config user.name "Your name"
$ git config user.email "your.name@example.com"
}}}

Those entries are store in `/path/to/repository/.git/config` and can edited anytime. git can show you the content of the `config` file.

{{{
$ git config -l
}}}

== Checkout ==
You can checkout the source code with the following command:

The main repository:

{{{
$ git clone git://git.mcs.anl.gov/bcfg2.git
}}}

The github mirror:

{{{
$ git clone https://github.com/solj/bcfg2.git
}}}

== Patches ==
We assume that you have checked out the source and are in the repository directory. First step is to create a new branch.

{{{
$ git checkout -b new_plugin
}}}

Make changes, add new features, write a plugin, or fix typos. Commit every change to your new branch.  

{{{
$ git add new_plugin.py
$ git commit -m "Plugin xyz added"
}}}

Note that no changes are in the `master` branch at the moment. But `git log` knows everything about your local commit.

{{{
$ git log --pretty=oneline -3
}}}

If you are happy with the result, make the patch.

{{{
git format-patch master --stdout > new_plugin.patch
}}}

Be aware that your patches need to be BSD licensed for mainline inclusion. 

Please send your patches to the [wiki:MailingList Bcfg mailing list] or open a ticket in the [http://trac.mcs.anl.gov/projects/bcfg2/newticket ticketing system].

== Fork / Pull request ==

[https://github.com/ github] provides tools for collaboration including a way to easy fork existing repositories. Go to the [https://github.com/solj/bcfg2 Bcfg2 github mirror] and fork this repository. For more detail please refer to [http://help.github.com/forking/ Forking a project]. Clone the fork:

{{{
$ git clone git@github.com:your_github_username/bcfg2.git
}}}

At the moment there is no connection to the upstream repository. You need to add another remote named "upstream" which points to the upstream repository.

{{{
$ cd bcfg2
$ git remote add upstream git://github.com/solj/bcfg2.git
$ git fetch upstream
}}}

Make changes, add new features, write a plugin, or fix typos. Then commit all changes.

{{{
$ git add new_file
$ git commit new_file -m "This is a new file"
$ git push origin master
}}}

If you are done, send a [http://help.github.com/pull-requests/ pull request].

Don't forget to pull-in changes from the upstream repository from time to time as described in the [http://help.github.com/forking/ Forking a project] document.

== Commit ==
Please visit the [wiki:GitAccess Git access] page or mail the [wiki:MailingList Bcfg mailing list] for details about the application for direct git repository access.

{{{
$ git add edited_file
$ git commit -m "A little comment about the change"
$ git push origin master
}}}