Development/Git/Configuration: Difference between revisions

    From KDE TechBase
     
    (32 intermediate revisions by 14 users not shown)
    Line 1: Line 1:
    == Git Configuration ==
    == Git Configuration ==


    How to set up Git for use in KDE.
    How to set up Git for use in KDE development.


    === Quick Start ===
    === 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:
    To quickly set up Git to just build a copy of KDE you do not need to perform any git configuration, however the sections below, starting from [[#URL_Renaming|URL Renaming]] will simplify using Git.
     
    * [[../Configuration#URL_Renaming|URL Renaming]]


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


    === Configuration Levels ===
    === Configuration Levels ===
    Your Git configuration operates at 3 levels:
    Your Git configuration operates at 3 levels:
    * System
    * System
    * User
    * User
    * Repository
    * Repository
    <br />
    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 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 [https://git-scm.com/docs/git-config#FILES ~/.gitconfig] file.


    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 {{Path|1=.git/config}} 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.
    {{Improve|The final sentence of this paragraph needs repair, a previous edit must have removed part of a sentence.}}


    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.
    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 at which some settings apply, 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.
    You can set Git settings either by directly editing the config files, but it is far safer to use the <code>git config</code> command.


    To set a Git setting at User level (i.e. in ~/.gitconfig):
    To set a Git setting at User level (i.e. in {{Path|1=~/.gitconfig}}):


      git config --global <key> <value>
      git config --global <key> <value>


    To set a Git setting at repo level (i.e in <repo>/.git/config):
    To set a Git setting at repo level (i.e in {{Path|1=<repo>/.git/config}}):


      cd <repo>
      cd <repo>
    Line 39: Line 38:
    === Basic Settings ===
    === 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:
    If you plan to commit to KDE Git, then you will need to set up git to use your https://identity.kde.org/ name and details to help identify your work:


      git config --global user.name <Your Real Name>
      git config --global user.name <Your Real Name>
      git config --global user.email <Your identity.kde.org email>
      git config --global user.email <Your identity.kde.org email>
    The name and email address you configure will be used as the author information for every commit you make. Note that in order for [https://community.kde.org/Sysadmin/GitKdeOrgManual#Commit_hook_keywords commit message keywords] such as BUG and CCBUG to work, your Bugzilla account email address has to match the email address used in your commits.


    To enable colored output when using git:
    To enable colored output when using git:
    Line 50: Line 51:
    === Commit Template ===
    === 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.
    The Commit Template is a standard layout for commit messages, usually containing instructions for how a project expects messages to be 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:
    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:
    Line 56: Line 57:
      git config --global commit.template <path/to/kdelibs/>.commit-template
      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 [https://github.com/KDE/kdelibs/blob/KDE/4.14/.commit-template here], save as ~/.commit-template, and configure to use that copy:
     
    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
      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:
    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>
      cd <repo>
      git config commit.template .commit-template
      git config commit.template .commit-template
    === Exclusion rules ===
    It's often necessary or desirable to limit the types of files that git will consider when commands like '''git&nbsp;status''' and '''git&nbsp;add''' or '''git&nbsp;add&nbsp;--all''' are run. There are 2 types of exclusion rules.
    The first, is a [https://git-scm.com/docs/gitignore .gitignore] file in the repository. This text file will contain a list of wildcard expressions to ignore files and/or dirs. It can also contain bash-like comments (#) in addition to blank lines.
    The second method is similar to the first, except it is specified globally and will override (and add to) settings specified on a per-repository basis. This file can be named whatever, wherever, as long as it is specified in your ~/.gitconfig file.
    An example .gitexcludes file can be found in kdelibs from [https://cgit.kde.org/kdelibs.git/plain/.gitexcludes?h=Active/Two here], save as {{Path|1=~/.gitexcludes}}, and configure to use that copy using:
    git config --global core.excludesfile ~/.gitexcludes
    Alternatively, edit {{Path|1=~/.gitconfig}} manually and specify:
    <br/>
    [core]
        excludesfile = ~/.gitexcludes
    Remember that this file is meant to be a global exclusion rule, so you probably shouldn't use it on a per-repo basis unless you really feel the need. The file excludes archive files (tar, gz, 7z, rar, etc.) as well as .directory, thumbs.db (Microsoft Windows file), .swp (swap file, used for vim and kate), as well as many many others.


    === Push Default ===
    === Push Default ===


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


      git config --global push.default nothing
      git config --global push.default nothing
    Line 79: Line 97:
      git config --global push.default 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.
    This will default to push to the remote branch your local branch is tracking, but if you set up your local branch incorrectly you may still accidentally push to the wrong remote.


    === URL Renaming ===
    === 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):
    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 file ({{Path|1=~/.gitconfig}}):


      [url "git://anongit.kde.org/"]
      <nowiki>[url "https://invent.kde.org/"]</nowiki>
         insteadOf = kde:
         insteadOf = kde:
      [url "git@git.kde.org:"]
      <nowiki>[url "ssh://git@invent.kde.org:"]</nowiki>
         pushInsteadOf = kde:
         pushInsteadOf = kde:


    == RSA Key fingerprint for git.kde.org==
    === Bash Auto-Completion ===
    c8:45:ba:89:85:11:78:b5:a4:09:d9:31:f6:7f:7c:79
     
    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 <code>git</code> on your command line followed by a space, then press the <keycap>tab</keycap> 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 [http://git.kernel.org/?p=git/git.git;a=blob_plain;f=contrib/completion/git-completion.bash;hb=HEAD 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 <code>git branch</code> and <code>git status</code>.
     
    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 {{Path|1=.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 {{Path|1=.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 + u+2)>
     
    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
    * u-1 = behind upstream by 1 commit
    * u+2 = ahead of upstream by 2 commits
    * u= = same as upstream
    <br />
    To enable showing the dirty (unstaged/staged) state, add the following line to your {{Path|1=.bashrc}} 'before' your PS1 setting:
     
    export GIT_PS1_SHOWDIRTYSTATE=1
     
    To enable showing the stashed state, add the following line to your {{Path|1=.bashrc}} ''before'' your PS1 setting:
     
    export GIT_PS1_SHOWSTASHSTATE=1
     
    To enable showing the untracked state, add the following line to your {{Path|1=.bashrc}} ''before'' your PS1 setting:
     
    export GIT_PS1_SHOWUNTRACKEDFILES=1
     
    To enable showing the upstream state, add the following line to your {{Path|1=.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
     
    === Multiple Work Branches ===
     
    You will often want to have more than one build environment in parallel, for example if you want to work on both stable and unstable branches at the same time.
     
    With Git you can easily have many work branches in your repository and easily switch between them.  The problem here however is that you can only work on the one branch at a time, and switching branches will usually trigger a massive rebuild of the entire repository. 
     
    One solution would be to have a separate repository clone for each branch you wish to work on in parallel, but this takes up more disk space, the clones and branches can easily get out of sync, and it makes forward/back porting bug fixes between branches more difficult.  If choosing this method then you should make each new clone from your initial local clone rather than from the main repo as this will be quicker.
     
    The ideal solution is for a single git repository clone to provide separate source directories for each branch you wish to work on, without performing full clone (what consumes disk space and requires fetching each clone separately). This can be achieved using the <code>[https://git-scm.com/docs/git-worktree git worktree]</code> command.  This creates what appears as a new clone in a separate folder but actually uses the same local clone.
     
    For example, assuming your have a kdelibs.git clone living in {{Path|1=~/kde/src/master/kdelibs}}, then the following commands will create a 4.6 work branch in {{Path|1=~/kde/src/4.6/kdelibs}}:
     
    cd ~/kde/src/master/kdelibs
    git worktree add ~/kde/src/4.6/kdelibs KDE/4.6
     
     
    {{Warning|The manpage for <code>git worktree</code> warns not to use this with repos containing submodules.}}
     
    == SSH host key fingerprints for git.kde.org==
    The SSH host server key fingerprints are as follows for both Git and Subversion access:
     
    * '''RSA-2048 (MD5)''': <code>32:c9:78:b1:1f:7c:2e:1c:12:26:62:1c:67:d0:6c:28</code>
    * '''RSA-2048 (SHA256)''': <code>rgF+nO+jdBEKOdowaOZBnaeWtAV6vquW4EjFafO1aaM</code>
    * '''ECDSA-256 (MD5)''': <code>cb:56:a3:74:a8:69:5c:f3:93:b0:dc:f9:05:1c:3f:9a</code>
    * '''ECDSA-256 (SHA256)''': <code>UutSIkXdSGgyxQxL35dDEEAD2Owel+zEdKZ5I/JMqrA</code>
    * '''ED25519-256 (MD5)''': <code>c8:99:54:39:84:9b:e5:39:1a:de:c6:6d:fa:4d:a4:e8</code>
    * '''ED25519-256 (SHA256)''': <code>tPgR57xn3BJVri4ncIMAtj/3Dxc9SB/ijOxORUTCQFk</code>

    Latest revision as of 07:58, 24 October 2020

    Git Configuration

    How to set up Git for use in KDE development.

    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 sections below, starting from URL Renaming 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.

    Warning
    This section needs improvements: Please help us to

    cleanup confusing sections and fix sections which contain a todo


    The final sentence of this paragraph needs repair, a previous edit must have removed part of a sentence.

    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 at which some settings apply, 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 https://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>
    

    The name and email address you configure will be used as the author information for every commit you make. Note that in order for commit message keywords such as BUG and CCBUG to work, your Bugzilla account email address has to match the email address used in your commits.

    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 be 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, save as ~/.commit-template, and configure to use that copy:

    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
    

    Exclusion rules

    It's often necessary or desirable to limit the types of files that git will consider when commands like git status and git add or git add --all are run. There are 2 types of exclusion rules.

    The first, is a .gitignore file in the repository. This text file will contain a list of wildcard expressions to ignore files and/or dirs. It can also contain bash-like comments (#) in addition to blank lines.

    The second method is similar to the first, except it is specified globally and will override (and add to) settings specified on a per-repository basis. This file can be named whatever, wherever, as long as it is specified in your ~/.gitconfig file.

    An example .gitexcludes file can be found in kdelibs from here, save as ~/.gitexcludes, and configure to use that copy using:

    git config --global core.excludesfile ~/.gitexcludes
    

    Alternatively, edit ~/.gitconfig manually and specify:

    [core]
       excludesfile = ~/.gitexcludes
    

    Remember that this file is meant to be a global exclusion rule, so you probably shouldn't use it on a per-repo basis unless you really feel the need. The file excludes archive files (tar, gz, 7z, rar, etc.) as well as .directory, thumbs.db (Microsoft Windows file), .swp (swap file, used for vim and kate), as well as many many others.

    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 set up 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 file (~/.gitconfig):

    [url "https://invent.kde.org/"]
        insteadOf = kde:
    [url "ssh://[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, then press 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 + u+2)>
    

    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
    • u-1 = behind upstream by 1 commit
    • u+2 = ahead of upstream by 2 commits
    • u= = same as 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
    

    Multiple Work Branches

    You will often want to have more than one build environment in parallel, for example if you want to work on both stable and unstable branches at the same time.

    With Git you can easily have many work branches in your repository and easily switch between them. The problem here however is that you can only work on the one branch at a time, and switching branches will usually trigger a massive rebuild of the entire repository.

    One solution would be to have a separate repository clone for each branch you wish to work on in parallel, but this takes up more disk space, the clones and branches can easily get out of sync, and it makes forward/back porting bug fixes between branches more difficult. If choosing this method then you should make each new clone from your initial local clone rather than from the main repo as this will be quicker.

    The ideal solution is for a single git repository clone to provide separate source directories for each branch you wish to work on, without performing full clone (what consumes disk space and requires fetching each clone separately). This can be achieved using the git worktree command. This creates what appears as a new clone in a separate folder but actually uses the same local clone.

    For example, assuming your have a kdelibs.git clone living in ~/kde/src/master/kdelibs, then the following commands will create a 4.6 work branch in ~/kde/src/4.6/kdelibs:

    cd ~/kde/src/master/kdelibs
    git worktree add ~/kde/src/4.6/kdelibs KDE/4.6
    


    Warning
    The manpage for git worktree warns not to use this with repos containing submodules.


    SSH host key fingerprints for git.kde.org

    The SSH host server key fingerprints are as follows for both Git and Subversion access:

    • RSA-2048 (MD5): 32:c9:78:b1:1f:7c:2e:1c:12:26:62:1c:67:d0:6c:28
    • RSA-2048 (SHA256): rgF+nO+jdBEKOdowaOZBnaeWtAV6vquW4EjFafO1aaM
    • ECDSA-256 (MD5): cb:56:a3:74:a8:69:5c:f3:93:b0:dc:f9:05:1c:3f:9a
    • ECDSA-256 (SHA256): UutSIkXdSGgyxQxL35dDEEAD2Owel+zEdKZ5I/JMqrA
    • ED25519-256 (MD5): c8:99:54:39:84:9b:e5:39:1a:de:c6:6d:fa:4d:a4:e8
    • ED25519-256 (SHA256): tPgR57xn3BJVri4ncIMAtj/3Dxc9SB/ijOxORUTCQFk