Skip to main content

init

CLI reference

Description

Since this command initializes the current workspace, you will always start with this command. It will create a folder called .esysrepo storing various configuration files as well as a few git repositories.

In its simplest form, the only required parameter of the init command is the URL of the git repository where the manifest is located (-u). Alternatively, --project-name / -p can resolve that URL from a known manifest directory (mutually exclusive with -u). --manifest-local / -l initializes from a local manifest file or folder without cloning (ADR-0034). Exactly one of -u, -p, or -l is required.

When using -u or -p, the steps then followed are:

  • Clone the git repository holding the manifest into a temporary folder inside the .esysrepo folder
  • Detect the format of the manifest file (Google repo tool format or ESysRepo native format), unless --google forces the Google path
  • Depending on the manifest's format, create configuration files and move the git repo with the manifest to its final folder inside .esysrepo

When using -l, the path is used in place (no clone). If it is a folder, the manifest is found in that folder (same detection order as after a clone). If it is a file, that file is the manifest. The workspace is --folder / -f or the current directory and may differ from the -l path. esysrepo init -l . initializes the current directory from a manifest already there.

The contents of .esysrepo are not secret, but they are not part of the public interface of the tool and may change between versions. Use only the command line tool itself and do not change by hand any of the files found in that folder, except where explicitly documented.

Usage

esysrepo init -u URL [options ...]
esysrepo init -p PROJECT [options ...]
esysrepo init -l PATH [options ...]

Options

Available options:

  • --manifest-url / -u URL: The URL of the git repository holding the manifest (required unless -p or -l is used)
  • --manifest-local / -l PATH: Local manifest file or folder (no clone; cannot be combined with -u or -p)
  • --manifest-branch / -b BRANCH: Manifest branch or revision to check out (git manifest source only; cannot be combined with -l)
  • --manifest-name / -m NAME: Manifest file name used to initialize the workspace (default default.xml). With -l pointing at a folder, selects that file in the folder. With -l pointing at a file, this option is an error
  • --project-name / -p NAME: Project name to look up in a manifest directory (resolves the manifest URL; cannot be combined with -u or -l)
  • --rev-set NAME: Native manifest revision-set name to select at init
  • --google / -g: Force Google repo tool manifest format (skip native .esysrepo.manifest* detection when both formats exist in the same repository)
  • --strict: Fail on unknown manifest XML for both Google repo and ESysRepo formats (default is tolerant / ignore-unknown). Stored as parse_mode in .esysrepo/config.json for later sync/load
  • --git-super / -s: Treat the repository as a git super project (not implemented yet)
  • --folder / -f PATH: Workspace folder to initialize (common option; default is the current directory).

Examples

To get the source code of ESysRepo, this would be the command line to use if using SSH (you need to be a contributor):

esysrepo init -u ssh://git@gitlab.com/libesys/esysbuild/manifest.git

Or simply using HTTPS, which will work for everyone:

esysrepo init -u https://gitlab.com/libesys/esysbuild/manifest.git

Initialize into a specific folder:

esysrepo init -u https://gitlab.com/libesys/esysbuild/manifest.git -f /path/to/ws

Initialize from a local superbuild that already has .esysrepo.manifest.xml:

esysrepo init -l .

Initialize a workspace from a local manifest file (no git repo required):

esysrepo init -l ./draft.esysrepo.manifest.xml -f /path/to/ws

Force Google repo format when a native ESysRepo manifest is also present:

esysrepo init -u https://example.com/manifest.git --google

Select a native revision-set at init:

esysrepo init -u https://example.com/manifest.git --rev-set develop