How to set up Git for use in KDE.
Your Git configuration operates at 3 levels:
The System Level sets up global Git configuration defaults for every User and Repository on your system. We will ignore these for our purposes as they are usually blank.
The User Level (aka Global) sets up the default configuration for a particular User to apply to all repositories used by that User. Settings made at this level will always override any matching System Level settings. The User Configuration is stored in your ~/.gitconfig file.
The Repository Level sets up the configuration for a particular Repository clone. Settings made at this level will always override any matching User or System Level settings. The Repository Configuration is stored in the repository .git/config file.
The recommended KDE Git Configuration will set some settings at a user level and some at a repository level. You may wish to change the level some settings apply at however as we will assume you only or mostly use Git for developing KDE.
You can set Git settings either by directly editing the config files, but it is far safer to use the git config command.
To set a Git setting at User level (i.e. in ~/.gitconfig):
git config --global <key> <value>
To set a Git setting at repo level (i.e in <repo>/.git/config):
cd <repo> git config <key> <value>
If you plan to commit to KDE Git, then you will need to set up git to use your identity.kde.org name and details to help identify your work:
git config --global user.name <Your Real Name> git config --global user.email <Your identity.kde.org email>
To enable colored output when using git:
git config --global color.ui true
The Commit Template is a standard layout for commit messages, usually containing instructions for how a project expects messages to formatted and what details are to be included. You can choose to set a User Level template as a default, then use any project level variations at a repo level.
It is recommended to use the kdelibs template as your default. Once you have cloned kdelibs then set as follows to ensure you use the latest available version:
git config --global commit.template <path/to/kdelibs/>.commit-template
[TODO: add the template to kdelibs!]
If you don't plan to have kdelibs cloned then download the kdelibs template from here (TBC) and save as ~/.commit-template and use that:
git config --global commit.template ~/.commit-template
Then, when cloning other KDE repositories, you should check to see if they have a project specific commit template, and if so you should set that at a repo level:
cd <repo> git config commit.template .commit-template
It is recommended for new Git users to set the push default to none:
git config --global push.default none
This option forces you to always enter the name of the remote branch you wish to push to, rather than using a default value. This is good practice as it ensures you push to the correct remote branch and avoid accidentally pushing all local branches to the remote.
More experienced users may wish to set the option to tracking:
git config --global push.default tracking
This will default to push to the remote branch your local branch is tracking, but if you setup your local branch incorrectly you may still accidentally push to the wrong remote.
Instead of having to remember and type in the different full git addresses for pulling and pushing, we recommend you manually add the following to your Git User Configuration (~/.gitconfig):
[url "git://anongit.kde.org/"] insteadOf = kde: [url "firstname.lastname@example.org:"] pushInsteadOf = kde: