Changes between Version 2 and Version 3 of WorkingConventions/Git/Submodules

Mar 23, 2014 10:44:31 AM (17 months ago)

add instructions for making changes to a submodule


  • WorkingConventions/Git/Submodules

    v2 v3  
    44{{{#!box warning
    5 This page and as well as the GitRepoReorganization is still work in progress;
     5This page as well as the GitRepoReorganization are still work in progress.
    7 See #8545 for the current state of affairs
     7See #8545 for the current state of affairs.
    1414 - [ "git submodule" manual page]
    1515 - [ Pro Git "6.6 Git Tools - Submodules" chapter]
     16 - [ Submodule Tutorial]
    1718== Cloning a fresh GHC source tree ==
    4950git submodule update --init
     53== Making changes to GHC submodules ==
     55It's very important to keep in mind that Git submodules track commits (i.e. not branches!) to avoid getting confused. Therefore, `git submodule update` will result in submodules having checked out a so-called [ detached HEAD].
     57So, in order to make change to a submodule you can either work directly on the detached HEAD, or checkout the respective branch the commit is supposed to be pointed at from. The example below will demonstrate the latter approach for the `utils/haddock` submodule:
     60# do this *before* making changes to the submodule
     61cd utils/haddock
     62git checkout master
     63git pull --rebase
     65# perform modifications and as many `git {add,rm,commit}`s as you deem necessary
     66$EDITOR src/somefile.hs
     68# finally, after you're ready to publish your changes, simply push the changes as for an ordinary Git repo
     69git push
     71# go back to ghc.git top-level
     72cd ../..
     75At this point, the remote `haddock.git` contains newer commits in the `master` brnach, which still need to be registered with `ghc.git`:
     78# if you want, you can inspect with `git submodule` and/or `git status` if there are submodules needing attention;
     79# specifically, both should report new commits in `util/haddock`
     80git submodule
     81git status
     83# Register the submodule update for the next `git commit` as you would any other file
     84# Note: You can think of submodule-references as virtual files which
     85#       contain a SHA1 string pointing to the submodule's commit.
     86git add util/haddock
     88# you can also add other changes in `ghc.git` (e.g. testsuite changes) and/or other submodules
     89# you need to update atomically with the next commit
     90git add testsuite/...
     92# prepare a commit, and make sure to mention the string `submodule` in the commit message
     93git commit -m 'update haddock submodule ... blablabla'
     95# finally, push the commit to the remote `ghc.git` repo
     96git push
     99{{{#!box note
     100There are server-side validation hooks in place to make sure for non-`wip/` branches that `ghc.git` never points to non-existing commits. Also, as a safe-guard against accidental submodule reference updates, the string `submodule` must occur somewhere in commit messages of commits updating submodule references.