Development/Git For LibreOffice Developers

TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate

• Wiki Home
• Development
• Design
• QA
• Events
• Documentation
• Website
• Localization
• Accessibility
• Marketing
• Diversity
• Wiki Help

• Overview
• Reporting Bugs
• How to build
• Code Overview
• Git Commands
• Debugging
• EasyHacks
• Release Plan
• FAQ
• Developers
• Extensions
• → Open Issues

Git is a Distributed version control system⁠ (DVCS). It is a very powerful yet simple system, but if you are unfamiliar with DVCS, it can be confusing. Thankfully there are great resources on the web to learn about Git. If you are not familiar with it, you should visit these links:

• https://learngitbranching.js.org/ for excellent visualized learning-by-doing.
• https://git-scm.com/book/ Pro Git book by Scott Chacon and Ben Straub
• Git is a Directed Acyclic Graph (archived by Wayback Machine⁠) -- if you know what a DAG is this is the quickest theory explanation
• https://www.youtube.com/watch?v=1ffBJ4sVUb4 for an easy and visual explanation.
• https://who-t.blogspot.com/2009/12/on-commit-messages.html How to write good commit messages.
• https://github.com/k88hudson/git-flight-rules A guide for gitstronauts about what to do when things go wrong.

The rest of this article will assume a basic working knowledge of Git.

Most of LibreOffice source code is in the core git repository, but a few modules are in separate repositories, translations, help and dictionaries. In most cases you probably won’t have to modify these repositories.

Managing Git branches

See: Development/Branches

A tip for displaying branch in your terminal prompt (Linux)

It is possible to display the branch you are working on in a style like this:

~/git/core/helpcontent2 (master)$

To achieve this, you can modify your PS1 prompt variable by adding the following to your $HOME/.bashrc:

source /usr/share/git/completion/git-prompt.sh # Note: the exact location of this file can vary depending on your system. On Debian-based systems, you can find the location with: dpkg -L git | grep prompt
export PS1='\[\033[01;32m\]\u@\h\[\033[01;34m\] \W\[\033[31m\]$(__git_ps1 " (%s)")\[\033[01;34m\]$\[\033[00m\] '

Another visual aid for the terminal is delta, which provides syntax highlighting for git, diff, and grep output.

Hack and commit on a stable branch

Stable branches are created from master or another stable branch to stabilize the code base for the release and further maintenance updates. There are some rules during the beta phase:

• Allowed are any changes in translations
• Allowed are any bug fixes
• Allowed are late features that are approved by the Engineering Steering Committee

There are more strict rules during the release candidate phase:

• Allowed are safe fixes that are reviewed by another person, see below
• Allowed are changes in translations; it is recommended to ask for review on the native l10n mailing list

Please, do not commit the fixes directly during the RC phase. Instead, please send your patch to gerrit or ask another developer for review on the libreoffice@lists.freedesktop.org mailing list, personal mail, on IRC or via the related bug entry. The fix should be committed by the reviewer using:

git commit -s --author='Author name <author@mail.address>'

What to do when git pull -r does not want to operate

It is usually due to local changes in your repository. You can either get rid of them, using:

git checkout -f
git pull -r

or stash them temporarily, and get them back again after the git pull -r:

git stash
git pull -r
git stash pop

Reset your modified repo to a “vanilla” repository

$ git reset --hard origin/master

The above command will discard all your local changes (whether committed or not) and reset the current branch that you are on to the one on the remote repository.

Delete untracked or ignored files

To clean out junk like temp files and old development logs and create a pristine working directory, give the command

$ git clean -fdx

Improve git cloning for slow network

If your network is slow, you can clone/checkout only the branch you need, or do a shallow/partial clone. You can do this from the LibreOffice mirror in GitHub, but remember to add a remote for the original repository.

For example, cloning from Github with depth=1 is like this:

git clone --depth=1 https://github.com/libreoffice/core

Then, you have to make sure the remote is set to the original repository. To do that, edit the .git/config file, so that the remote section is like this:

[remote "origin"]
	url = git://git.libreoffice.org/core
	fetch = +refs/heads/*:refs/remotes/origin/*

Reorder, squash and in general tweak your local history: git rebase -i

git rebase -i is a powerful tool that allows you to “rewrite” your local history.

Warning: This should only be done on commits that have not been pushed to master or a release branch yet!

Let’s say you are on master and the last 3 commits are A,B,C=HEAD but C is actually a correction of the commit A that you missed before committing B. So what you would want to do is to merge A and C together and end-up with A',B as history.

To do that you can give the command:

git branch safehead HEAD

This is just in case something goes very wrong and you want to just undo everything and go back to the initial state.

git rebase -i HEAD~3

This should bring, in your favorite editor (as set by the variable $EDITOR) a list of the last 3 commits, from the oldest to the newest (the reverse order than normally in git log), so C is the last of the list:

pick 726fe9c enable localization of extension descriptions in mysqlc
pick 9ab6ecf fix en-US only build
pick a18bfb0 Revert "enable localization of extension descriptions in sdext"

# Rebase 1846533..a18bfb0 onto 1846533
#
# Commands:
#  p, pick = use commit
#  r, reword = use commit, but edit the commit message
#  e, edit = use commit, but stop for amending
#  s, squash = use commit, but meld into previous commit
#  f, fixup = like "squash", but discard this commit's log message
#  x <cmd>, exec <cmd> = Run a shell command <cmd>, and stop if it fails
#
# If you remove a line here THAT COMMIT WILL BE LOST.
# However, if you remove everything, the rebase will be aborted.
#

Edit it, moving commit C one-up and changing its action to squash:

pick 726fe9c enable localization of extension descriptions in mysqlc
squash a18bfb0 Revert "enable localization of extension descriptions in sdext"
pick 9ab6ecf fix en-US only build

Then save and exit the editor.

Now you can edit the commit message of the merged commit:

   # This is a combination of 2 commits.
   # The first commit's message is:
   
   enable localization of extension descriptions in mysqlc
   
   Change-Id: I7141eea0fe7f72408da0d2a5ebe4a5e2891b6b7d
   
   # This is the 2nd commit message:
   
   Revert "enable localization of extension descriptions in sdext"
   
   Change-Id: Iff01d31792a13a14ea720c477417217af0c01642

Note: If you intend to push the commit to gerrit, the ChangeId line is crucial: gerrit uses it to find an existing patch that will be updated with a new revision. So make sure to take the ChangeId line from the appropriate commit (usually the one you already uploaded to gerrit before), do not edit it, and remove the ChangeId line of the less important commit that you want to get rid of.

Once you have combined the 2 commit messages, save and exit again.

If everything went nicely you should be on master with your HEAD on B and A+C fused into one commit A', just before B. If things went wrong and you are lost:

git rebase --abort

If things are not reverted to the way they should (compounded wrongness) you can say this to pretend nothing ever happened:

git reset --hard safehead

Getting and using commit access

In order to get commit access you need to be "sponsored". Once you've submitted patches and got yourself recognised this won't be a problem, but it's best to wait until you're asked or ask for someone to sponsor you.