Using Git submodules for binary assets

News about the Cafu Engine. Subscribe to the related ImageCafu News feed to stay informed.
User avatar
Carsten
Site Admin
Posts:2170
Joined:2004-08-19, 13:46
Location:Germany
Contact:
Using Git submodules for binary assets

Post by Carsten » 2016-08-08, 12:35

We have always had the problem that Cafu requires a large amount of binary assets (mostly texture images) for being useful: Making a good first impression, demonstrate important features, getting started with mapping – all these require proper binary assets. Even C++ core hackers enjoy seeing a couple of texture images occasionally. :cheesy:

One approach to shipping such binary assets is committing them straight to the Cafu source code repository. While this is very simple and convenient, it also means that we'd be dragging along all these heavyweight binaries in the version history forever. Even though the current texture images volume of 180 MiB doesn't seem to be much by today's standards, this never worked well, neither with the formerly used Subversion nor with the current Git repositories. As we might also work with much larger and frequently changing binaries in the future, adding them to the Cafu source code repository, which is intended to be kept lean and clean, is even more prohibitive.

Therefore, as an alternative, we put all the texture images into a zip archive and uploaded it to the cafu.de web server. While this seemed to be a viable and simple enough approach that in fact we have used for years, in the long term it turned out to be a lot more cumbersome than expected: The zip archive must be regularly updated, rebuilt, checked for problems and uploaded, and anyone who uses Cafu must download and extract it, carefully making sure that the extraction puts all files into their proper places.

Fortunately, we can now do much better: Keeping all texture images in a dedicated repository that we include from the main (source code) repository as a Git submodule addresses (almost) all of these problems: The source code repository keeps lightweight and independent while it is reasonably possible to pull the related binary assets just into the right place at the right "edition".

You can learn more about Git submodules e.g. in the Pro Git book in chapter Git Tools – Submodules. Unfortunately, Git submodules too are not as easy to use as they could be, but there is well-founded hope that the situation is going to improve. For now, if you've pulled the latest changes into your local repository, run these commands in order to populate the Games/DeathMatch/Textures directory with the proper files from the submodule:

Code: Select all

$ git submodule init
$ git submodule update
For existing checkouts, this is necessary only once.

If you clone the Cafu repository entirely anew, add option --recursive to the clone command in order to init and update the submodules automatically:

Code: Select all

$ git clone --recursive https://bitbucket.org/cafu/cafu.git Cafu
I have updated the instructions at Getting Started with the Cafu Source Code accordingly.
Best regards,
Carsten
Post Reply

Who is online

Users browsing this forum: No registered users and 5 guests