Skip to main content

Creating and sharing a repos-lock.csv file

The repos-lock.csv file is a snapshot of your entire repository setup. It captures the exact state of all your repositories including branches, commit SHAs, LST locations, and organizational hierarchy. Think of it as the package-lock.json of repository management – it ensures that anyone on your team can recreate your exact setup with a single command.

This file is automatically generated and maintained by the Moderne CLI as you work with your repositories. It lives in the .moderne folder and grows richer with metadata as various CLI commands process your repositories.

In this guide, we'll walk you through everything you need to know about creating and distributing a repos-lock.csv file.

Creating the file​

The repos-lock.csv file is built incrementally through a series of CLI commands. Here's the typical workflow:

1. Create a repos.csv file​

First, you'll need to create a repos.csv file. This file can be as simple as just having a list of repository URLs:

cloneUrl
https://github.com/openrewrite/rewrite
https://github.com/openrewrite/rewrite-maven-plugin

2. Clone the repositories​

Once you have that repos.csv file, the next step is to clone all of the repositories to your system by running the following command:

mod git sync csv --with-sources /path/to/your/repos /path/to/csv

This creates the directory structure and clones the source code. As part of running this command, a basic repos-lock.csv file will also be created in the .moderne folder.

3. Run mod build​

With the repositories cloned to your system, the next step is to run the mod build command.

mod build /path/to/your/repos

On top of creating the LSTs for all of your repositories, this command will also analyze your repositories and update the repos-lock.csv file with:

  • The actual branch that was checked out
  • The commit SHA (changeset) for each repository
  • Build metadata and status

4. Run mod publish​

The last step you'll need to do is to run the mod publish command (presuming you have configured an artifact repository to publish to):

mod publish /path/to/your/repos

This adds the publishUri column to your repos-lock.csv file, recording where each LST was published.

At this point, your repos-lock.csv file contains everything needed to recreate your exact setup – repository locations, exact commits, and LST locations. You should then share that with your team.

Sharing and using the file​

The repos-lock.csv file is designed for team collaboration. One developer can set up the repositories, build the LSTs, and then share this file with the entire team.

For the person creating the file​

After running through the creation steps above, share the repos-lock.csv file with your team. You can find it in the .moderne folder at the root of your repository structure.

We recommend storing it somewhere that's easily accessible by people at your company.

For team members using the file​

Team members can recreate your exact setup by running this command:

mod git sync csv /path/to/your/repos /path/to/repos-lock.csv

This command will:

  • Create the same directory structure
  • Download the pre-built LSTs from your artifact repository
  • Set up the exact same repository state

Note that by default, this won't clone the source code – just the LSTs, which is usually all that's needed for analysis and recipe execution. If source code is needed later, team members can run:

mod git sync csv /path/to/your/repos /path/to/repos-lock.csv --with-sources

Key benefits​

The repos-lock.csv file provides several important advantages:

  • Reproducibility: Every developer gets the exact same setup
  • Speed: Team members download pre-built LSTs instead of building them locally
  • Consistency: Everyone works with the same repository versions and LST data
  • Self-contained: The file contains all the information needed – no external configuration required

The repos-lock.csv file essentially turns "it works on my machine" into "it works on every machine" by capturing and sharing the complete state of your repository setup.