Repository Template

Authors:

• Gabriel Nützi @gabyx
• Cyril Matthey-Doret @cmdoret

What Is This?

This is a repository template giving you a top-level structure with the following features.

• Git & Git Large File System (LFS) configured.
• Nix development shell enabled with direnv and .envrc.
• Language specific best-practice setup for rust, go or python.
• Formatting with treefmt-nix.
• Githooks (optional) which runs pre-commit checks:
  • Git LFS checks.
  • Format with treefmt-nix.
• Devcontainer: not-yet-provided (future, based on Nix dev shell)

Usage

Over Container

bash mkdir repo podman run -it -v "$(pwd)/repo:/workspace" \ ghcr.io/sdsc-ordes/repository-template:latest \ -t "<language>" -d "." [-- ["args-to-copier"...]]

[!CAUTION]

Using docker above will create root-owned files on your machine (by default without some user namespacing setup etc.), we strongly recommend using podman instead.

See arguments explanations here.

By Cloning

Clone this repository to some place of your choice.

Apply the templates with copier using the following:

bash cd repo && git pull just create -t "<language>" -d "<destination>" [-- ["args-to-copier"...]]

See arguments explanations here.

Arguments

• <destination> is the destination folder where you want to place your new repository.

• <language> is one of the following templates:

  • generic: For a generic repository without any language specific needs.
  • python: For python toolchain with uv and other good tooling.
  • rust: For a Rust toolchain with cargo
  • go: For a default Go toolchain.

• [args-to-copier...] are optional arguments passed to copier. If you want to overwrite by default use -w and not answer Y all the time and -l to apply all defaults to inspect:

shell just create -t <language> -d <destination> -- -w -l

Structure

The following describes the content of the top-level directories:

• docs : All documentation-related files. The README.md should link into this folder.
• examples : Examples showing how to use this software component.
• external : Third party resources imported with git submodules, vendir or other tools.
• src: Where your source code lives.
• tools: Specific needs which are not part of the source:
  • configs: config related files for certain tools like, e.g. formatters, linters etc.
  • nix: Nix related stuff.
  • ci: CI related tooling/scripts.
  • scripts: Additional scripts complementing the justfile etc.

Generic Template

• Template Source
• Demo Rendering

Toolchain

Source

• Command-Runner: just
• Nix Shell: devenv provided Nix shell using toolchain-generic.nix.
• Formatter: Tree format with treefmt-nix and enabled languages

Rust Template

• Template Source
• Demo Rendering

Toolchain

Source

• Toolchain: Rust toolchain on nightly
• Build-Tool: cargo
• LSP: rust-analyzer
• Formatter: rustfmt

Go Template

• Template Source
• Demo Rendering

Toolchain

Source

• Compiler: go at 1.23.X
• Build-Tool: go
• LSP: gopls
• Formatter: gofmt, goimports, golines

Python Template

Template Source

Toolchain

• Source

• Demo Rendering

• Interpreter: python at 3.12

• Build-Tool: uv

• LSP: pyright

• Formatter: ruff

CI Implementations

Github Actions

The following workflows are defined:

• format.yaml: Formats the whole repository with treefmt, configured over Nix. For it to work with cachix (a Nix CI caching mechanism) you need to define two secrets in Settings -> Secrets & variables -> Actions -> Repositories secrets:

  • CACHIX_CACHE_NAME: The cache name you created on cachix.org. This is free for public caches, which is acceptable for OSS repositories.
  • CACHIX_AUTH_TOKEN: The access token created on cachix.org for this cache CACHIX_CACHE_NAME.

Development

Read first the Contribution Guidelines.

For technical documentation on setup and development, see the Development Guide

Copyright

Copyright © 2025-2028 Swiss Data Science Center (SDSC), www.datascience.ch. All rights reserved. The SDSC is jointly established and legally represented by the École Polytechnique Fédérale de Lausanne (EPFL) and the Eidgenössische Technische Hochschule Zürich (ETH Zürich). This copyright encompasses all materials, software, documentation, and other content created and developed by the SDSC.