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


Ignore:
Timestamp:
Mar 23, 2014 10:44:31 AM (16 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}}}