Software Engineer | Technical Evangelist

Blog PostsResume

Link one repository's subdirectory to another

Loklak, a distributed social media message search server, generates its documenations automatically using Continuous Integration. It generates the documentation in the gh-pages branch of its repository. From there, the documentation is linked and updated in the gh-pages branch of repository.

The method with which Loklak links the documentations from their respective subprojects to the repository is by using subtrees. Stating the git documentation,

"Subtrees allow subprojects to be included within a subdirectory of the main project, optionally including the subproject's entire history. A subtree is just a subdirectory that can be committed to, branched, and merged along with your project in any way you want."

What this means is that with the help of subtrees, we can link any project to our project keeping it locally in a subdirectory of our main repository. This is done in such a way that the local content of that project can easily be synced with the original project through a simple git command.


A representation of how Loklak currently uses subtrees to link the repositories is as follows.

git clone --quiet --branch=gh-pages central-docs
cd central docs

git subtree pull --prefix=server gh-pages --squash -m "Update server subtree"

git subtree split:

The problem with the way documentation is generated currently is that the method is very bloated. The markup of the documentation is first compiled in each sub-projects’s repository and then aggregated in the repository. What we intend to do now is to keep all the markup documentation in the docs folder of the respective repositories and then create subtrees from these folders to a master repository. From the master repository, we then intend to compile the markups to generate the HTML pages.

Intended Implementation:

To implement this we will be making use of subtree split command.

  1. Create a subtree from the docs directory and moves it to a new branch documentation.
  2. Clone the master repository. (This is the repository we intend to link the subdirectory with.)
  3. Retrieve the latest content from the subproject.
  4. Push changes.

     # Create subtree from docs directory
     git subtree --prefix=docs/ split -b documentation
     # Clone the master repository
     git clone --quiet --branch=master loklak_docs
     cd loklak_docs
     # Sync content with the subproject.
     git subtree pull --prefix=raw/server ../loklak_server documentation --squash -m "Update server subtree"
     if [ $? -ne 0 ]; then
       git subtree add --prefix=raw/server ../loklak_server documentation --squash -m "Update server subtree"
     # Publish the changes
     git push -fq origin master > /dev/null 2>&1


© 2019 | Ujjwal Bhardwaj. All Rights Reserved.