Skip to content

Commit

Permalink
docs: make 'git pull' automatically update submodules (runfinch#274)
Browse files Browse the repository at this point in the history
## Why

Before this PR, if the pinned commit of any submodule is updated in the
remote tracking branch, folks need to explicitly add `--recurse` when
running `git pull` to also update the submodule to the updated commit.
Regarding our usage of submodules, since we only consume upstream
updates (i.e., not modifying them), and there're not many submodules,
which means that recursively updating them won't take a lot of time,
it's likely that we always want to recursively update all the submodules
when running `git pull`.

## Steps to Reproduce

Setup:

```sh
git clone --recurse-submodules --branch v0.4.0 https://github.com/runfinch/finch.git
cd finch
git checkout -b demo
git branch --set-upstream-to origin/main
git pull
```

Submodules are not updated:

```sh
➜  finch git:(demo) ✗ git --no-pager diff
diff --git a/deps/finch-core b/deps/finch-core
index eef2102..01e6162 160000
--- a/deps/finch-core
+++ b/deps/finch-core
@@ -1 +1 @@
-Subproject commit eef21029b89d7db00bddc6e426e4405c920b13ed
+Subproject commit 01e6162d6fd76fddb9d8ef59845c782a0b6ebafd
```

Fix it:

```sh
➜  finch git:(demo) ✗ git config submodule.recurse true
➜  finch git:(demo) ✗ git pull
Fetching submodule deps/finch-core
Fetching submodule deps/finch-core/src/lima
Fetching submodule deps/finch-core/src/socket_vmnet
Already up to date.
Submodule path 'deps/finch-core': checked out 'eef21029b89d7db00bddc6e426e4405c920b13ed'
Submodule path 'deps/finch-core/src/socket_vmnet': checked out 'ee27d206872fc861c2993264be93d2ccc2740f9c'
➜  finch git:(demo) git --no-pager diff
➜  finch git:(demo) echo $?
0
```

## Notes

If `submodule.stickyRecursiveClone` is set, and the repository is cloned
with `--recurse-submodules`, it'd also work, but it does not account for
the case when the repository is already cloned without
`--recurse-submodules`, so setting `git config submodule.recurse true`
seems to be the simplest way that works for all scenarios.

## License Acceptance

By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache 2.0 license.

Signed-off-by: Hsing-Yu (David) Chen <[email protected]>
  • Loading branch information
davidhsingyuchen authored Mar 8, 2023
1 parent e2d9232 commit 2516dc5
Showing 1 changed file with 6 additions and 2 deletions.
8 changes: 6 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,9 +139,13 @@ If the repo is already cloned, but the submodules are not pulled yet, the follow
git submodule update --init --recursive
```

After cloning the repo, run `make` to build the binary.
After cloning the repo, run the following command to make subsequent `git pull` to also update submodules to the versions specified in the upstream branch.

The binary in `_output` can be directly used. E.g. initializing the vm and display the version
```shell
git config submodule.recurse true
```

Then run `make` to build the binary. The binary in `_output` can be directly used. E.g. initializing the vm and display the version

```sh
./_output/bin/finch vm init
Expand Down

0 comments on commit 2516dc5

Please sign in to comment.