Development/Submodules

From The Document Foundation Wiki
Jump to: navigation, search

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

By default your submodules 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 pushurl for the <submodule> you are working on or you will not be able to commit.

editor .git/modules/<submodule>/config

And in the section [remote "origin"] add:

pushurl = ssh://logerrit/<submodule>

(if the working submodule is helpcontent2, you should set help in place of <submodule>)

Alternatively, use

git config remote.origin.pushurl ssh://logerrit/<submodule>

If you want to create a new commit, for let's say the master branch. go to the submodule's directory and create a local branch based on the current HEAD there:

cd <submodule>
git checkout -b my_branch

Edit the submodule's files and commit your changes.

Then push them to gerrit:

git push origin my_branch:refs/for/master

At that point you can go back to core and run

git submodule update

That will reset your <submodule> module to the detached HEAD it needs according to the state of core.

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

If you have commit access to the submodule, you can also push directly

git push origin my_branch:master

but if someone pushed something directly of via a gerrit patch review 'submission' then you run in the usually deny non-fastforward push.

Re-syncing is a bit more complex: you need to go to core and

./g pull -r

Then go back to the submodule which will be once again on a detached HEAD (the new HEAD associated with core)...

cd <submodule>

You need to re-checkout your branch :

git checkout my_branch

Rebase it :

git rebase origin/master

And finally push again:

git push origin my_branch:master


Again gerrit will detect a push in master of <submodule> and automatically generate a commit on core to reflect that change... so after pushing, you can go back to core and run ./g pull -r that will bring core into a state where git status should be clean (except for non-tracking crap you may have :-) )

Once your submodule commit is fully integrated, you can delete 'my_branch' :

cd <submodule>
git branch -D my_branch

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 after submodules if you shoot yourself in the foot.

Missing Change-ID

If you are only cloning the submodules repo and gerrit complains about missing Change-Ids you can get the commit hook that adds the Change-ID with:

gitdir=$(git rev-parse --git-dir); scp -p -P 29418 user_name@gerrit.libreoffice.org:hooks/commit-msg ${gitdir}/hooks/

Replace user_name with your gerrit user name. After that use git commit --amend to update the commit msg and let git add the Change-ID.