From d34d7af6f49477da5884d474a6f8b437fa2b39d1 Mon Sep 17 00:00:00 2001 From: Troy McConaghy Date: Mon, 19 Nov 2018 15:20:36 +0100 Subject: [PATCH] Added notes on "Living with Submodules" --- README.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/README.md b/README.md index 64d345bf..1fd39e34 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ --- +- [Living with Submodules](#living-with-submodules) - [Content](#content) - [Content Files](#content-files) - [External Content Files](#external-content-files) @@ -34,6 +35,26 @@ - [Authors](#authors) - [License](#license) +## Living with Submodules + +This Git repo has [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules). They are the subdirectories of `external/`. Each one is basically another Git repo, i.e. an external Git repo that just _looks_ like it's part of this Git repo. It's very easy to get Git into a confusing state when there are submodules. If you follow the following tips, you should probably be okay: + +1. Clone this repo using: + ```bash + git clone --recurse-submodules git@github.com:oceanprotocol/docs.git + ``` +1. Don't edit anything in the submodules (i.e. in `external/`). Instead, edit it over in the other Git repository and merge your changes over there. +1. Get all the submodules up-to-date using: + ```bash + git submodule update --remote + ``` + That will get each submodule up-to-date with the HEAD commit of some branch in a remote repository. Which branch? That's set in the `.gitmodules` file. You can check the current commit hashes of all the submodules using `git submodule status` +1. Before doing any `git checkout ...` or other normal Git operations, do this: + ```bash + git config --global submodule.recurse true + ``` + That's like adding the `--recurse-submodules` option to all those Git commands (except for `git clone`) so you don't have to. + ## Content The documentation is split in multiple sections whose content lives in this repo: