======How to work with git repositories======
Required packages:
   * git-core
   * git-core-slug (suggested, >= 0.12)
   * rpm-build-tools >= 4.5-3

=====Prepare working dirs====

Move existing (CVS-based) ''~/rpm'' directory:
  mv ~/rpm ~/rpm.cvs
  
Prepare new directory:
  builder --init-rpm-dir

=====Building package=====
For now one needs to use local ''~/rpm/packages/builder'':
  cd ~/rpm/packages/
  ./builder -v -bp python-msgpack
===== Set your configuration ====

Your identity (NOTE: This sets globally):
<code>
git config --global user.name "Your Name"
git config --global user.email <email>
</code>

One can do it per package too in each ''./.git/config'' file: <file ini>
[user]
    email = <your_login>@pld-linux.org
    name = Your Name
</file>
but as for now one needs to set it in each package fetched.

If you have an RW access to PLD Linux repositories please use
your PLD Linux alias ''<your_login>@pld-linux.org>'' as email.

If you have github account and wish github mirror being updated with your credentials (referencing github resources, closing pull request), you may wish to setup SSH Agent forwarding so that github sync is performed with your credentials. You need to have same key or github key in ssh agent. Such ''~/.ssh/config'' will enable SSH agent forwarding when pushing: <file - ~/.ssh/config>
Host git.pld-linux.org
    ForwardAgent    yes
</file>

Additionally some useful git config:

Enable colored diffs ([[http://live.gnome.org/Git/Developers|reference]]) <code>
git config --global color.ui auto
</code>

Add ''git st'' and some other aliases ([[https://git.wiki.kernel.org/index.php/Aliases|reference]]) <code>
git config --global alias.st status
git config --global alias.ci commit
git config --global alias.up pull --rebase
git config --global alias.ssh '!ssh git@git.pld-linux.org'
</code>

when pushing in git-core >= 1.8.0 ([[http://lists.pld-linux.org/mailman/pipermail/pld-devel-en/2012-October/023231.html|reference]])
<code>
git config --global push.default simple
</code>

=====Download package=====

   git clone git://git.pld-linux.org/packages/<package>
   cd <package>

or

   slug.py clone <package>
   cd ~/rpm/packages/<package>


If you have RW access you can also use ssh access:

   git clone git@git.pld-linux.org:packages/<package>
   cd <package>

In directory you will find local copy of main branch in the upstream
repository. It is usually called ''master''.

==Remark:=== 
In git repositories there are two kind of branches: local ones on which
you work, and remote ones, which tracks changes in upstream
repository. The remote branches live in a different namespaces: remotes. The
default remote is called ''origin'', so the main remote branch is
usually called ''origin/master''. Clone, besides other things,  creates a local
''master'' branch that tracks remote origin/master branch.
=====Commit your changes=====
First you put your changes in a staging area - the index:
    git add file

Then you can produce a commit from contents of index:

    git commit

You can also skip the staging area by:

    git commit -a

It will commit the changes in every tracked file. If you want to add new file
to the repository you still need to add it explicitly with ''git add''

**Remarks:**
    * Commit in git are atomic so put related changes to multiple files into one commit.
    * Write nice commit logs.

=====Push your changes upstream=====

Most git operations change only your local repository. If you want to update upstream
repository you need to push your changes. However if you have cloned the packages using git
directly from git daemon, you need first to set URL for pushing (for obvious reason anonymous pushes
using git daemon are not supported):

    git remote set-url --add --push origin git@git.pld-linux.org:packages/<package>

If you have cloned the repository using slug.py too, the URL for pushing has been already set by slug.py.

Then you can push your changes:

    git push origin master

where master is a name of branch you want to push. If you are not certain
whether you will push to the right branch you can first try:

   git push --dry-run origin master

===== Modify commit messages =====

commit messages can be annotated with ''git notes'' feature.

Read more on mailing list: http://lists.pld-linux.org/mailman/pipermail/pld-devel-en/2012-July/022786.html
=====Update your repository=====

   git fetch origin

It will update all your remote-tracking branches. It will not change your local branches or working directory. For this
you need to commit your changes to your local branch and then explicitly merge changes from remote branch to it. For example:

   git merge origin/master

Alternatively to get a more clean history you can rebase your changes on top of remote branch:

   git rebase origin/master
=====Work on  some other branch=====

First you need to create your local branch. If you want to follow the remote branch foo, the simplest way is to:

  git checkout <branch>

It will create local branch <branch> which tracks remote branch origin/<branch>.

List all your local branches:

   git branch

All remote branches:

   git branch -r

All branches (local and remote)

   git branch -a

===== Pushing big files =====

You shouldn't (can't) push bigger files than 2MiB. Big files, including patches, should be stored in distfiles.

If the file is accessible by url, just add ''# SourceX-md5: '' or ''# PatchX-md5: '' comment to the spec, and the file itself does not need to be added to git index. remove/revert if you already did. If the file is generated locally, you need to upload it to distfiles before pushing.

There's exception if you can't do that (is too hard to do due local modifications), you can add the patch filename into ''.bigfiles'' file. See [[http://lists.pld-linux.org/mailman/pipermail/pld-devel-en/2012-October/023210.html|pld-devel-en post]].

After you found you pushed and was rejected by big file restriction, you can fix it like this (assuming it was only single commit):
<code bash>
echo 7.3.640 > .bigfiles
git add .bigfiles
git commit --amend
git push origin master
</code>
=====Graphical repository browser=====

Sometimes it is useful to see a graphical representation of all branches. It can obtained with:

   gitk  --all

You can limit the set of commits shown by by gitk. For example to present only two branches:

   gitk branch1 branch2


=====Create new package=====

  slug.py init <package>
  
To be able to use ''builder'' script or push your changes upstream
you have to create local branch in newly created repository:

  cd <package-repo>
  touch <specfile>
  git add <specfile>
  git commit -m 'Init commit'
  
slug.py init and git add can be replaced with:
  
  ./builder -a <specfile>
  
and then:
  
  git push -u origin master
====Use template specs for new packages ====
Often it is good idea to start working over new spec starting from spec templates available:
  git clone git://git.pld-linux.org/projects/template-specs.git

===== Rename package =====
Assume we want lowercase python-Flask:
  $ ssh git@git.pld-linux.org   move python-Flask  python-flask
try build to download new version:
  nice builder -v python-flask
rename spec file:
  $ cd python-flask/
  $ git mv python-Flask.spec  python-flask.spec 
Update spec with name change and commit changes.

=====More information on git=====

 [[http://progit.org/book/|"Pro git" book]]
  
  
======RW access ussing ssh public keys======
===== Listing your keys =====
To list currently available keys:
  ssh  git@git.pld-linux.org sskm list
  
If you use different keypair (''.ssh/id_rsa_pld_linux'' in my case) to connect specify it:
  ssh -i ~/.ssh/id_rsa_pld_linux git@git.pld-linux.org sskm list
  
One can even make keypair change transperent by adding ''~/.ssh/config'':
  Host git.pld-linux.org
     IdentityFile ~/.ssh/id_rsa_pld_linux
     
===== Adding new key =====
Generate pair ( ''id_rsa_matkor_pld_linux_app4'' and ''id_rsa_matkor_pld_linux_app4.pub'' in my case)
   ssh-keygen -f ~/.ssh/id_rsa_matkor_pld_linux_app4

<note warning>
**IMPORTANT**: ''@app4'' needs to be unique. use ''sskm list'' to see what names are used
</note>
   
Add it (as key ''app4'' in my case):
  cat ~/.ssh/id_rsa_matkor_pld_linux_app4.pub  | ssh git@git.pld-linux.org sskm add @app4

Confirm (using -i of new key ):
  ssh -i ~/.ssh/id_rsa_matkor_pld_linux_app4   git@git.pld-linux.org sskm confirm-add @app4
===== More to read =====
http://sitaramc.github.com/gitolite/sskm.html