================================================================================
                            Working with submodules
================================================================================
--------------------------------------------------------------------------------
Informations
--------------------------------------------------------------------------------

When working with submodules,
- The file .gitmodules describe the state of the submodules for the main repo.
  For instance it gives the commit to target, the location, ...
- Submodules are in a detached HEAD state, meaning the copy point to a specific
  commit. No history is stored.

--------------------------------------------------------------------------------
Cloning a repository
--------------------------------------------------------------------------------

$ git clone <repo_url>
$ cd <repo>
$ git submodule update --init --recursive

--init: reads the .gitmodules and registers each submodules in the main repo
configuration.
update: downloads the exact version referenced in the main repo.

--------------------------------------------------------------------------------
Adding a submodule
--------------------------------------------------------------------------------

$ git submodule add <repo_url> <repo>
$ git add .
$ git commit
$ git push

--------------------------------------------------------------------------------
Working on a submodule then updating the main repo
--------------------------------------------------------------------------------

The main repo config reference a fixed commit. To update the content of a
submodule, it is needed to go into the submodule directory within the main repo
and pull the changes. The main repo is now in dirty state and it needs to
commit the update of the submodule.

$ cd <submodule>
$ git fetch
$ git checkout --detach <branch>
or
$ git checkout <tag>
$ git pull
$ cd ..
$ git status
$ git add <submodule>
$ git commit
$ git push

--------------------------------------------------------------------------------
Working on the main repo then updating it elsewhere
--------------------------------------------------------------------------------

When updating the main repo, if another working copy exists elsewhere and pull
the changes. The submodule commit reference can change. It is possible to get
the compatible version by udating the submodule.

$ git submodule update

--------------------------------------------------------------------------------
More commands
--------------------------------------------------------------------------------

$ git submodule update --remote

This command ignores the specific hash currently recorded into the main repo.
It gets the latest changes from the default tracking branch and put the
submodule in detached HEAD state and the main repo in dirty state.

$ git config submodule.<submodule>.branch <branch>

Sets the default tracking branch for the submodule.
