Development/Submodules

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

Working on core

If you are working on core only the submodules should track where they need to be based on the commit you are in in core. If, when you do git status, you see something like

git status
# On branch k6
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#       modified:   dictionaries (new commits)
#

you can rectify the situation by running

git submodule update

That will reset the submodule to the commit it should be on according to core's information, and git status after that should not contain any reference to submodules.

Working in submodules

The recommended way to get submodules is to add autogen options like --with-lang=<language code(s)>, --with-help=html or --with-myspell-dicts in your autogen.input file. The mentioned options fetch translations, help and dictionaries respectively.

If you decide to manually clone a submodule, run this command after the clone is completed:

git submodule update --init <submodule>

By default your submodule repository is in a state called 'detached HEAD'. This means that the checked-out commit -- which is the one that the super-project (core) needs -- is not associated with a local branch name.

Don't forget to add a correct push URL for the <submodule> you are working on or you will not be able to commit.

git remote set-url --push origin ssh://logerrit/<submodule>

For example, if the working submodule is helpcontent2, you should set help in place of <submodule>.

If you want to create a new change, create a new branch:

cd <submodule>
git checkout -b my_branch origin/master

Edit the submodule's files and commit your changes inside the submodule directory.

Then push them to Gerrit from within the submodule directory:

git push origin my_branch:refs/for/master

On the gerrit side, when your patch is reviewed and submitted, gerrit will automatically create a commit on core to reflect the submodule change so that everybody will see the change at their next ./g pull -r.

Once your submodule patch is merged, you can delete 'my_branch':

./g checkout master
cd <submodule>
git branch -D my_branch

By using the ./g script, you do not need to worry about git submodule update.

Note: If you are not pulling from gerrit.libreoffice.org, but from freedesktop for example, it may take a minute before a pull from core will get you the automatic commit created on core by gerrit. This is not a problem for anyone else because the commit on core is always after the commit on the submodules, so anyone else who pulls will not have your submodule commit before core knows about it.

There are of course other workflows that one can use, and plenty of other situations one can drive oneself into. The advice is: stick to the one described here. If you want to be creative, good for you, but then do not whine, if you shoot yourself in the foot.

Missing Change-ID

If you are only cloning the submodules repository and gerrit complains about missing Change-Ids you can get the commit hook that adds the Change-ID by running this in the core directory:

./g -z

After that use git commit --amend to update the commit message and let git add the Change-ID.