Skip to main content

Getting Started

This page takes you from nothing installed to a working, assembled source tree.

Gimera reads a gimera.yml file at the root of your project and materialises every repository it lists into your workspace. Most of the time you are not writing that file — you are joining a project that already has one, and you need gimera to turn a nearly empty checkout into a complete Odoo tree.

Before you start​

  • Python 3 and pipx. If you do not have pipx: brew install pipx on macOS, sudo apt-get install pipx on Ubuntu/Debian.
  • git, configured with the SSH key you use for GitHub.
  • Access to the repositories your project pulls in. This is the step people trip over. A gimera.yml that lists git@github.com:odoo/enterprise will fail for anyone without access to that repository, and the failure appears as a git permission error partway through, not as a clear message up front.
  • Disk space and patience for the first run. A full Odoo tree is around 10 GB.

Install gimera​

pipx install gimera

pipx keeps gimera in its own virtual environment, so it cannot collide with the Python packages of whatever project you point it at.

To check it is there:

gimera --help

There is no gimera --version. To see which version you have:

pipx list

To upgrade later:

pipx upgrade gimera

Assemble an existing project​

This is the common case. You have cloned a repository that contains a gimera.yml, and the addon directories it refers to are missing or empty.

git clone --branch 19.0 git@github.com:Odoo-Ninjas/zebroo-sync.git
cd zebroo-sync
gimera apply -r

Run it from the directory containing gimera.yml — the project root.

-r (recursive) matters: a repository gimera pulls in may carry its own gimera.yml, and without -r those nested repositories are skipped and you get a tree that looks complete but is missing addons.

What apply does for each entry, in order:

  1. Clones the repository, or fetches into it if a cache copy already exists
  2. Checks out the pinned sha, or the tip of branch if no sha is set
  3. Applies any patches listed for it
  4. Places the result at path — merged into your tree for integrated entries, or left as a genuine submodule for submodule ones

The first run is slow. Gimera caches every repository under ~/.cache/gimera, so the second project that needs the Odoo core reuses the copy rather than downloading it again.

:::note First run looks like it has hung After "resolving deltas" finishes, gimera spends a minute or more building a compressed cache archive with no output. It has not stalled. Interrupting it here is the one thing that reliably breaks the cache — see Troubleshooting. :::

Check what you got​

gimera status

This reports each repository in gimera.yml, whether it is present, and whether anything in it is dirty. Then look at the tree itself:

ls odoo addons_OCA

You should see real source, not empty directories. Empty directories after a run that reported success almost always mean a nested gimera.yml was skipped — re-run with -r.

Start a project from scratch​

If you are the one creating the configuration, write a minimal gimera.yml at the project root:

common:
  vars:
    VERSION: "19.0"

repos:
  - url: git@github.com:odoo/odoo
    branch: ${VERSION}
    path: odoo
    type: integrated

Then add further repositories with the CLI rather than editing by hand — it keeps the formatting consistent and validates as it goes:

gimera add \
  --url https://github.com/OCA/web.git \
  --branch 19.0 \
  --path addons_OCA/web \
  --type integrated

gimera apply addons_OCA/web

Naming the path as a positional argument limits the run to that one repository instead of re-checking everything.

Declare the Odoo version once as a variable and reference it with ${VERSION}. Upgrading the project to a new Odoo release then means editing one line.

Commit the result​

After a run, gimera writes the commit it actually resolved back into the sha field of each entry. Those changes are the record of what your project is built from, so they belong in git:

git diff gimera.yml
git add gimera.yml && git commit -m "chore: pin gimera shas"

Review that diff before committing. It is the one place where "an upstream repository moved" becomes visible.

Integrated repositories are a different matter. Their files are merged into your workspace, so a plain git commit at the project root does not push anything back upstream. Use gimera commit for that — see Command Line.

Everyday commands​

You want toCommand
Assemble a freshly cloned projectgimera apply -r
Pull in the latest upstream commitsgimera apply -u
Re-check one repository onlygimera apply <path>
See what is present and what is dirtygimera status
Add a repository to the configgimera add --url … --branch … --path … --type …
Push changes made inside an integrated repogimera commit <repo> "<message>"
Diagnose a failing patchgimera apply -v <path>

Troubleshooting​

Permission denied (publickey) partway through a run. Your SSH key does not have access to one of the repositories listed. Find which one from the line above the error and ask for access; gimera cannot work around it.

The run stops on a corrupted cache archive. Usually the result of interrupting the first run while it built the cache. Delete the archive for that repository and run again:

rm ~/.cache/gimera/github.com-odoo-odoo.tar.gz
gimera apply -r

To watch the cache being built rather than guessing, check that the file is still growing:

ls -lh ~/.cache/gimera

A patch fails to apply. The default output is not enough to tell you why. Re-run that one repository verbosely:

gimera apply -v addons_OCA/web

A patch that no longer applies normally means upstream moved underneath it. Pin the sha back to the commit the patch was written against, or regenerate the patch with gimera edit-patch.

Everything is dirty and you want a clean slate. gimera clean and gimera purge remove dirty items — including uncommitted work inside integrated repositories, which is not recoverable. Run gimera status first and read it.

Next​