Infrastructure/Git/Configuration: Difference between revisions

From KDE Community Wiki
Line 124: Line 124:
You can learn more about customizing your bash prompt at http://www.tldp.org/HOWTO/Bash-Prompt-HOWTO/.
You can learn more about customizing your bash prompt at http://www.tldp.org/HOWTO/Bash-Prompt-HOWTO/.


You can also have the prompt show the 'dirty' status of your repo, i.e. if you have unstaged, staged or uncommited changes, and whether your branch is behind or ahead of HEAD.
You can also have the prompt show the 'dirty' status of your repo, i.e. if you have uncommited changes, and whether your branch differs from upstream HEAD:


The git-completion.bash docs state:
* * = unstaged changes
* + = staged changes
* $ = stashed changes
* % = untracked files
* < = behind upstream
* > = ahead of upstream
* <> = diverged from upstream


In addition, if you set GIT_PS1_SHOWDIRTYSTATE to a nonempty
To enable showing the dirty (unstaged/staged) state, add the following line to your .bashrc 'before' your PS1 setting:
value, unstaged (*) and staged (+) changes will be shown next
to the branch name.  You can configure this per-repository
with the bash.showDirtyState variable, which defaults to true
once GIT_PS1_SHOWDIRTYSTATE is enabled.


  You can also see if currently something is stashed, by setting
  export GIT_PS1_SHOWDIRTYSTATE=1
GIT_PS1_SHOWSTASHSTATE to a nonempty value. If something is stashed,
then a '$' will be shown next to the branch name.


If you would like to see if there're untracked files, then you can
To enable showing the stashed state, add the following line to your .bashrc 'before' your PS1 setting:
set GIT_PS1_SHOWUNTRACKEDFILES to a nonempty value. If there're
untracked files, then a '%' will be shown next to the branch name.


  If you would like to see the difference between HEAD and its
  export GIT_PS1_SHOWSTASHSTATE=1
  upstream, set GIT_PS1_SHOWUPSTREAM="auto".  A "<" indicates
 
you are behind, ">" indicates you are ahead, and "<>"
To enable showing the untracked state, add the following line to your .bashrc 'before' your PS1 setting:
indicates you have diverged.  You can further control
 
behaviour by setting GIT_PS1_SHOWUPSTREAM to a space-separated
  export GIT_PS1_SHOWUNTRACKEDFILES=1
list of values:
 
    verbose      show number of commits ahead/behind (+/-) upstream
To enable showing the upstream state, add the following line to your .bashrc 'before' your PS1 setting:
    legacy        don't use the '--count' option available in recent
 
                  versions of git-rev-list
export GIT_PS1_SHOWUPSTREAM="auto verbose"
    git           always compare HEAD to @{upstream}
 
    svn          always compare HEAD to your SVN upstream
To not show the number of commits ahead or behind remove the "verbose" flag.
By default, __git_ps1 will compare HEAD to your SVN upstream
 
if it can find one, or @{upstream} otherwise.  Once you have
To disable showing the dirty state for any one repo:
  set GIT_PS1_SHOWUPSTREAM, you can override it on a
 
  per-repository basis by setting the bash.showUpstream config
cd <repo>
variable.
git config bash.showDirtyState false
 
To disable showing the upstream state for any one repo:
 
  cd <repo>
  git config bash.showUpstream false


== RSA Key fingerprint for git.kde.org==
== RSA Key fingerprint for git.kde.org==
c8:45:ba:89:85:11:78:b5:a4:09:d9:31:f6:7f:7c:79
c8:45:ba:89:85:11:78:b5:a4:09:d9:31:f6:7f:7c:79

Revision as of 17:58, 18 March 2011

Git Configuration

How to set up Git for use in KDE.

Quick Start

To quickly set up git to just build a copy of KDE you do not need to perform any git configuration, however the following steps will simplify using Git:

If you plan to commit to a KDE repository using Git then you should follow all the steps on this page.

Configuration Levels

Your Git configuration operates at 3 levels:

  • System
  • User
  • Repository

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>

Basic Settings

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

Commit Template

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

If you don't plan to have kdelibs cloned then download the kdelibs template from here and save as ~/.commit-template and use that:

git config --global commit.template ~/.commit-template

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

Push Default

It is recommended for new Git users to set the push default to nothing:

git config --global push.default nothing

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.

URL Renaming

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 "[email protected]:"]
    pushInsteadOf = kde:

Bash Auto-Completion

Bash auto-completion for Git commands and branches may or may not work out-of-the-box for you depending on how Git is installed on your system. To see if you have auto-completion already working type git on your command line followed by a space and hit the tab key twice. If you see a list of available git commands then you have Git auto-completion enabled.

If auto-completion does not work for you then you can download the git-completion.bash script and follow the instructions inside it.

Bash Prompt

If you have git-completion.bash installed, you can also add details like the branch name and dirty status to your command prompt, which will save repeated uses of git branch and git status.

To activate this, you need to add the following to your $PS1 environment variable:

$(__git_ps1 " (%s)")

Note that in the " (%s)" part the %s variable is replaced with the branch name, the rest of the text between the quotes is up to you.

If you have not set a PS1 value yourself, then you are likely to be using your distro default value which you can find out by typing:

echo $PS1

To change this for your user, edit your .bashrc and copy the result of the echo command into there, then change it to add the Git branch.

For example, if echo $PS1 shows:

$(ppwd \l)\u@\h:\w>

then add the following to your .bashrc:

PS1='$(ppwd \l)\u@\h:\w$(__git_ps1 " (%s)")> ' 

which will show your prompt as follows:

odysseus@argo:~/kde/src/trunk/KDE/kdelibs (master)>

You can learn more about customizing your bash prompt at http://www.tldp.org/HOWTO/Bash-Prompt-HOWTO/.

You can also have the prompt show the 'dirty' status of your repo, i.e. if you have uncommited changes, and whether your branch differs from upstream HEAD:

  • * = unstaged changes
  • + = staged changes
  • $ = stashed changes
  • % = untracked files
  • < = behind upstream
  • > = ahead of upstream
  • <> = diverged from upstream

To enable showing the dirty (unstaged/staged) state, add the following line to your .bashrc 'before' your PS1 setting:

export GIT_PS1_SHOWDIRTYSTATE=1

To enable showing the stashed state, add the following line to your .bashrc 'before' your PS1 setting:

export GIT_PS1_SHOWSTASHSTATE=1

To enable showing the untracked state, add the following line to your .bashrc 'before' your PS1 setting:

export GIT_PS1_SHOWUNTRACKEDFILES=1

To enable showing the upstream state, add the following line to your .bashrc 'before' your PS1 setting:

export GIT_PS1_SHOWUPSTREAM="auto verbose"

To not show the number of commits ahead or behind remove the "verbose" flag.

To disable showing the dirty state for any one repo:

cd <repo>
git config bash.showDirtyState false

To disable showing the upstream state for any one repo:

cd <repo>
git config bash.showUpstream false

RSA Key fingerprint for git.kde.org

c8:45:ba:89:85:11:78:b5:a4:09:d9:31:f6:7f:7c:79