Submodules

What is a git submodule?

A git submodule is a folder in a git repository that is itself a git repository. This is useful for example, if you have some highly re-usable library code that you're storing in a git repo. And you'd now like to use that library in a different project. Copying the files over would work, but it means that you'd lose out on any future changes made to the library unless you manually copied the files over again. Submodules aim to solve this problem.

Why are we using git submodules?

We're using git submodules in a slightly different use case. In our scenario we want everyone who uses dashboard to be able to receive updates to the core features of dashboard without having to conduct a lengthy merge process every time. Imagine this example:

1. Dashboard is a single repository with no submodule
2. You fork the repo and replace "RedPandaHacks I" with "YourHackathon I" in every file.
3. The HackHer413 team releases a sweet new update to Dashboard that adds a searchbar to the projects page
4. You try to pull these new changes into your repo, but now you have to deal with conflicts :(

Using submodules allows us to mostly circumvent this issue and only force you to deal with conflicts when we make changes to the configuration folder. Remember, everything in there is basically just website copy and options, so we'd only do this if we're adding a new option for you to try out or if we need to change the format of the configuration to accommodate a new feature. These merges should be very infrequent and relatively painless!

An additional benefit to the submodule approach is that it means the HackUMass & HackHer413 teams do not have to work on an internal fork of the Dashboard repo. That means that the repo you see, is the one we develop. This ensures that any improvements we make for ourselves all go back to the open source community. And the same applies for any of your contributions. No one's event will require a hard fork of the dashboard project. Everyone works on and contributes to the same repository, thus making it better for the whole community. The problem of hard internal forks was one we noticed many other similar projects faced, and we wanted to ensure that by design we could avoid this problem.

How do git submodules work?

Git submodules work by tracking a specific commit within the submodule (this is why the submodule repo if you cd into it, is in a detached head state).

Essentially your outside git repo is storing the remote url and commit hash of the submodule. When you run git pull inside the submodule repo (or git submodule update --remote in the main repo) the submodule folder pulls the latest commit from remote and checks it out (again, in a detatched state). At this stage, you will have uncommitted changes in the main repo, because your submodule commit hash doesn’t match what the main git repo expects it to be. You can commit these changes, and the main repo will now track the newer commit of the submodule.

Our instructions essentially are telling you to update your submodule as if it were a regular repo (just remember to checkout a branch when you're in there). And then from the dashboard repository, add commits that only track changes to the .gitmodules file where you're changed the remote URL of the submodule, and the commit hash that git keeps track of so it knows which version of the submodule you're using. This way you have 0 meaningful commits on the dashboard repository as an end user. If something bad happens, you can just nuke the repo and re-clone it, changing the submodule URL and re-initializing the module to point to your configuration as you see fit. Additionally as a bonus, you're be able to keep track of the version history of your own copy & configuration which could be useful.