- Custom Development
To keep the code base modular we use submodules (Online documentation: Git Tools - Submodules, Using submodules and subrepositories). Some submodules are used by all the projects, while some are more specific. Their code is kept general so it compiles with many flavors of GCC/g++.
The screenshot below shows https://github.com/DephyInc/fx-rigid-mn. We will use it as an example to highlight a few things.
To clone the latest version of a repository in a fresh directory, with its submodules populated, use this command:
git clone --recursive -b branchName https://github.com/DephyInc/RepositoryName.git
If we use the fx-rigid-mn repository as an example, to clone the dev branch we use:
git clone --recursive -b dev https://github.com/DephyInc/fx-rigid-mn.git
When you do that, you get the submodule version that was committed with the main project. As an example, flexsea-comm will be at version 46874a2. This might not be the latest, but its what was committed. Unless the developer made a mistake while committing or pushing the code, this project should compile and work with no tweaking necessary. Because is worth a thousand words, lets explore a typical situation. Our simplified system has two main projects (fx-rigid-mn and fx-rigid-ex) and two submodules (flexsea-comm and flexsea-projects).
Each rectangle is a commit, with its number written in the box. The text in the commit message. Time is on the vertical axis: lower is more recent. To simplify the story, we will assume that a single developer is doing all the changes. The letters track the commits in time.
A) At the starting point, all four projects are at commit #1 (with their heads pointing to commit #1), and everything works. This hypothetical system has -mn and -ex communicating using 24-byte packets, and a state machine living in -projects goes through different impedance coefficients and setpoints.
B) A bug is found in flexsea-comm. A correction is made, and the code is committed (flexsea-comm #2).
C) Oh, turns out we need bigger packets! We are now using 48-byte packets (flexsea-user commit #3) D) We update fx-rigid-mn to use the latest version of flexsea-comm (#3). flexsea-projects didn't change, we keep using commit #1. (fx-rigid-mn commit #2)
E) Eventually fx-rigid-ex will be updated to the newest submodules, and the demo will be fixed.
git clone --recursive repoAddress/repoName.git cd repoName git checkout hash git submodule update --recursive
You can get the hash sequence from the Dephy team as a sequence, or as a URL, or you can find it from the commit log. If you browse through the log, once you find the commit you want click on its dot:
In that case, it brings us to this URL: https://github.com/DephyInc/fx-rigid-mn/commit/e922c5dd0464679cb43cfef4f56fff87e33e3b75. The long alphanumerical sequence is the hash. To clone it, one would do:
git clone --recursive https://github.com/DephyInc/fx-rigid-mn.git cd fx-rigid-mn git checkout e922c5dd0464679cb43cfef4f56fff87e33e3b75 git submodule update --recursive
Cloning a project with –recursive will always lead to “detached heads”. Using the previous example, if at the end of the example we clone fx-rigid-mn commit #1, the flexsea-comm repo will be at commit #1 while its head is at commit #3; that's what git calls a detached head.
As terrible as they sound, detached heads are not a problem if you only want to use the code as-is. If you want to do changes to the code, and commit them, you should start by attaching the head. It's a simple as doing “git pull branchName”, doing your work, and committing it. Always be aware that the new code you are pulling has never been tested with your main project; it can break compilation, and/or it can break your system. Be mindful and careful.