---
name: "kas-lock"
section: "1"
platform: "linux"
package: "kas"
version: "4.8.1-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/kas-lock"
---

# kas-lock(1)

kas lock plugin

## NAME

kas-lock - kas lock plugin

## SYNOPSIS

```
kas lock [-h] [--skip STEP] [--force-checkout] [--update] [--indent INDENT]
         [--sort]
         [config]
```

## DESCRIPTION

Create and update kas project lockfiles.

This plugin implements the **kas lock** command.

When this command is executed a locking spec is created which only contains the exact commit of each repository. This is used to pin the commit of floating branches and tags, while still keeping an easy update path. The lockfile is created next to the first file on the kas cmdline. For details on the locking support, see *kas.includehandler.IncludeHandler*.

**NOTE:**

- •

  all referenced repositories are checked out to resolve cross-repo configs

- •

  all branches are resolved before patches are applied

**Updating lockfiles**

When updating lockfiles, kas attempts to update the repository revisions in the lockfile that defines the revision. If a repository is exclusively locked in an external lockfile, this lock is not updated (we cannot modify an external repository). However, if the revision is also defined in a local lockfile, it is updated in the local lockfile.

The algorithm for determining where to pin the revision of a repository is as follows:

- 1\.

  Find all repositories that have a floating ref (i.e. no commit). Assign to *to-lock* list

- 2\.

  Iterate over all lockfiles (in include order)

  - 1\.

    for each repository, check if it is locked in the current file

    - 1\.

      if lock is up to date, remove from *to-lock* list

    - 2\.

      else if lockfile is internal, update lockfile, remove from *to-lock* list

    - 3\.

      else (repo is locked in external lockfile): mark repo external

- 3\.

  Remove all repos with *external* marks from *to-lock* list

- 4\.

  Add all remaining repos in *to-lock* list to topmost lockfile, create if needed

**Examples**

The lockfile is created as **kas-project.lock.yml**. Call again to regenerate lockfile:

```
kas lock --update kas-project.yml
```

The generated lockfile will automatically be used to pin the revisions:

```
kas build kas-project.yml
```

Note, that the lockfiles should be checked-in into the VCS.

## OPTIONS

**Positional Arguments**

- **config**

  Config file(s), separated by colon. Using .config.yaml in KAS\_WORK\_DIR if none is specified.

**Named Arguments**

- **--skip=\[\]**

  Skip build steps. To skip more than one step, use this argument multiple times.

  Possible choices: setup\_dir, setup\_home, init\_setup\_repos, repo\_setup\_loop, finish\_setup\_repos, repos\_checkout, repos\_check\_signatures, repos\_apply\_patches, setup\_environ, write\_bbconfig

- **--force-checkout=False**

  Always checkout the desired commit/branch/tag of each repository, discarding any local changes

- **--update=False**

  Pull new upstream changes to the desired branch even if it is already checked out locally

- **--indent=4**

  Line indent (# of spaces, default: 4)

- **--sort=False**

  Alphanumerically sort keys in output

## SEE ALSO

**[kas-project-config(1)](/kas-project-config/1.md)**, **[kas-dump(1)](/kas-dump/1.md)**, **[kas-build(1)](/kas-build/1.md)**

## KAS

Part of the **[kas(1)](/kas/1.md)** suite.

## AUTHOR

Daniel Wagner, Jan Kiszka, Claudius Heine

## COPYRIGHT

Siemens and contributors, 2017-2025