Project templates and reusability

Project templates

Templates can help you to standardize your software development process.

GitHub repository templates

You can turn an existing repository into a template, so you and others can generate new repositories with the same directory structure, branches, and files. Note, the template repository cannot include files stored using Git LFS.

Repository templates

• Creating a template repository
• Repository template example to make your code more compliant with FAIR principles

Cookiecutter for Python

Cookiecutter creates Python projects from project templates. The advantage of using Cookiecutter is that new projects are set up quickly from a standardized template structure and can include everything needed to get started on a project, such as directory layouts, sample code, and even integrations with tools and services.

Tutorials

• Tutorial for Cookiecutter
• For installation instructions, have a look at Cookiecutter installation instructions.

Cookiecutter templates

• Cookiecutter templates on GitHub
• Cookiecutter PyPackage: template for distributing Python libraries.
  • GitHub - cookiecutter-pypackage
  • GitHub - Netherlands eScience Center template
• Cookiecutter Machine Learning: template for machine learning projects.

Reusing projects and repositories

One of the easiest ways to reuse code across projects is by packaging it into an installable library that can be used as a dependency. Alternatively, you can integrate external code into your project using Git submodules or Git subtree.

Practices to avoid

• Storing commonly-used folders in a separate folder on your system and adding the folder to the PATH. Other users/developers will not have access to these folders.
• Direct copy-and-pasting of code as you lose any upstream changes to the external repository.

What’s the Difference?

Feature	Git Submodules	Git Subtree
How it works	Adds an external repository inside your project as a separate Git reference.	Merges an external repository’s contents into your project’s directory structure.
Version Control	Tracks a specific commit of the external repository (not automatically updated).	The external repository’s commits are fully merged into your project’s commit history.
Updating	Requires running git submodule update --remote to pull new changes.	Updates by merging changes from the external repository into your project.
Ideal For	Keeping external code separate while still using it in your project.	Fully integrating external code while keeping its history.

In short:

• Use Git submodules when you want to include an external repository but keep it separate, track its exact version, and update it manually.
• Use Git subtree if you want to fully integrate an external repository’s code into your project while keeping its commit history.

Git submodules

A Git submodule allows you to add a separate Git repository inside another repository as a subdirectory. It is a record that points to a specific commit in another external repository. Submodules are useful for incorporating external code or libraries into your project while keeping them separate and easily updatable.

Git submodule commands

Adding a submodule

To add an external repository as a submodule inside your project, use:

git submodule add <repo-url>

Cloning a repository with submodules

When cloning a repository that contains submodules, follow these steps: 1. Clone the repository:

git clone <repo-url>

2. Initialize the submodules:

git submodule init

3. Fetch the submodule content:

git submodule update

Alternatively, you can use the shorthand command to clone and initialize submodules:

git clone --recurse-submodules <repo-url>

Updating submodules

To update the submodules to the latest commit, use:

git submodule update --remote

Learn more

• Simplified Git submodules tutorial
• Guide on Git submodules - comprehensive guide that covers everything from the basics to advanced workflows

If you are using GitHub Desktop

If you are using GitHub Desktop, be aware that there can be limitations when working with submodules. While GitHub Desktop supports basic submodule functionality, some operations may require using the command line. Known issues include

• difficulties in initializing submodules
• switching branches with submodules
• visualizing submodule changes.

For more details, check out this discussion or visit the GitHub Desktop issue tracker.

Git subtree

Unlike Git submodules, Git subtree merges the history of one repository into another as a subdirectory. This makes the external repository’s files appear as if they are part of your project while still allowing updates.

For more details, check out this Git subtree guide.