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 dev.loklak.org repository.
The method with which Loklak links the documentations from their respective subprojects to the dev.loklak.org 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 firstname.lastname@example.org/dev.loklak.org.git central-docs cd central docs git subtree pull --prefix=server https://github.com/loklak/loklak_server.git 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 dev.loklak.org 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.
To implement this we will be making use of
subtree split command.
- Create a subtree from the docs directory and moves it to a new branch documentation.
- Clone the master repository. (This is the repository we intend to link the subdirectory with.)
- Retrieve the latest content from the subproject.
# Create subtree from docs directory git subtree --prefix=docs/ split -b documentation # Clone the master repository git clone --quiet --branch=master email@example.com:loklak/dev.loklak.org.git 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" fi # Publish the changes git push -fq origin master > /dev/null 2>&1