codchi init

Initialize a new code machine

Synopsis

codchi init -y|--dont-prompt-N|--no-build -p|--use-nixpkgs-a|--auth -b|--branch -r|--tag-c|--commit -v|--verbose... -q|--quiet... --json -h|--help <MACHINE_NAME> URL MODULE_PATHS

Description

A code machine usually has one module that resides in the repository of the project you want to develop. To create a machine with this module, use the following command. Only the url to the repository is mandatory. Codchi will try to guess the rest of the information and prompt you if neccessary.

Options

• -y, --dont-prompt
  Dont prompt for confirmation and accept all of Codchis defaults. Usefull for using Codchi in scripts
• -N, --no-build
  Dont automatically build this machine after this command completes
• -p, --use-nixpkgs=USE_NIXPKGS
  Whether to use Nixpkgs from the local Codchi installation or the remote URL. See the "Which nixpkgs should I use?" section of codchi init for more details.
  By default Codchi will use remote if defines a nixpkgs input in its flake. Otherwise it will use the local nixpkgs.
  *possible values: *local, remote
• -a, --auth=AUTH
  Authorisation string for private repositories. Generally, the syntax is <user>:<token> or just <token>.
  GitHub for example has something like ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx whereas GitLab uses oauth2:glpat-xxxxxxxxxxxxxxxxxxxx.
• -b, --branch=BRANCH
  The git branch to use for the code machine module
• -r, --tag=TAG
  The git tag to use for the code machine module
• -c, --commit=COMMIT
  The git commit to use for the code machine module
• -v, --verbose
  Increase logging verbosity
• -q, --quiet
  Decrease logging verbosity
• --json
  Produce output in JSON format, suitable for consumption by another program
• -h, --help
  Print help (see a summary with -h)
• <MACHINE_NAME>
  Name of the code machine
• URL
  HTTP(S) URL to the git repository which holds the Codchi module.
  When omitted Codchi will create a base machine without modules.
• MODULE_PATHS
  A list of flake paths to the Codchi modules you whish to add. Currently supported: codchiModules. or nixosModules.. If not sure which modules are available, leave this empty. Codchi will prompt you with a list of possible options.
  With --dont-prompt this argument is required.

Extra

Which nixpkgs should I use?

Since every code machine is a NixOS system, it needs a version of nixpkgs (the collection containing all Nix programs). There are two options:

1. Use Codchi's nixpkgs: Every release of codchi has a pinned version of nixpkgs which is consistent across all code machines on a given host system. Because the Nix store is shared among all machines, this results in fewer package downloads, saves disk space and is faster during installation or updates. The downside is that code machines aren't perfectly reproducibile anymore, since the nixpkgs version can change with every Codchi version. In reality this shouldn't be a big deal because Codchi adheres to NixOS's release schedule (every 6 months) and keeps nixpkgs consistent across this timespan.
2. Use the module's nixpkgs: If a module of a code machine has a nixpkgs input inside its flake.nix, the code machine can use (Nix language: "follow") it.
   • Pro: Exact reproducibility among machines with the same module and nixpkgs.
   • Con: More packages to download, more disk space and slower during installation and updates.

Examples

Create a machine with a Java devenv:

codchi init <MACHINE_NAME> https://github.com/aformatik/codchi nixosModules.jvm

Create a machine with Codchi's devenv (rust):

codchi init <MACHINE_NAME> https://github.com/aformatik/codchi nixosModules.codchi

Let Codchi search for available modules in <REPO_URL> and prompt you with it:

codchi init <MACHINE_NAME> <REPO_URL>

Create an empty base machine:

codchi init <MACHINE_NAME>