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


Ignore:
Timestamp:
Mar 23, 2014 10:44:31 AM (17 months ago)
Author:
hvr
Comment:

add instructions for making changes to a submodule

Legend:

Unmodified
Added
Removed
Modified
  • WorkingConventions/Git/Submodules

    v2 v3  
    33
    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.
    66
    7 See #8545 for the current state of affairs
     7See #8545 for the current state of affairs.
    88}}}
    99
     
    1414 - [http://git-scm.com/docs/git-submodule "git submodule" manual page]
    1515 - [http://git-scm.com/book/en/Git-Tools-Submodules Pro Git "6.6 Git Tools - Submodules" chapter]
     16 - [http://www.vogella.com/tutorials/Git/article.html#submodules Submodule Tutorial]
    1617
    1718== Cloning a fresh GHC source tree ==
     
    4950git submodule update --init
    5051}}}
     52
     53== Making changes to GHC submodules ==
     54
     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 [http://alblue.bandlem.com/2011/08/git-tip-of-week-detached-heads.html detached HEAD].
     56
     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:
     58
     59{{{#!sh
     60# do this *before* making changes to the submodule
     61cd utils/haddock
     62git checkout master
     63git pull --rebase
     64
     65# perform modifications and as many `git {add,rm,commit}`s as you deem necessary
     66$EDITOR src/somefile.hs
     67
     68# finally, after you're ready to publish your changes, simply push the changes as for an ordinary Git repo
     69git push
     70
     71# go back to ghc.git top-level
     72cd ../..
     73}}}
     74
     75At this point, the remote `haddock.git` contains newer commits in the `master` brnach, which still need to be registered with `ghc.git`:
     76
     77{{{#!sh
     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
     82
     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
     87
     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/...
     91
     92# prepare a commit, and make sure to mention the string `submodule` in the commit message
     93git commit -m 'update haddock submodule ... blablabla'
     94
     95# finally, push the commit to the remote `ghc.git` repo
     96git push
     97}}}
     98
     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.
     101}}}