{"id":18733549,"url":"https://github.com/insightsengineering/locksmith","last_synced_at":"2025-07-01T01:37:16.681Z","repository":{"id":206019756,"uuid":"704081887","full_name":"insightsengineering/locksmith","owner":"insightsengineering","description":"renv.lock generator","archived":false,"fork":false,"pushed_at":"2025-04-17T06:44:27.000Z","size":385,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-19T23:43:52.689Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://insightsengineering.github.io/locksmith/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/insightsengineering.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"custom":["https://pharmaverse.org"]}},"created_at":"2023-10-12T13:53:34.000Z","updated_at":"2025-04-17T22:21:54.000Z","dependencies_parsed_at":"2023-11-21T12:46:35.195Z","dependency_job_id":"8a8eb1d1-d351-403f-97e4-a195ac2630e5","html_url":"https://github.com/insightsengineering/locksmith","commit_stats":null,"previous_names":["insightsengineering/locksmith"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/insightsengineering/locksmith","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightsengineering%2Flocksmith","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightsengineering%2Flocksmith/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightsengineering%2Flocksmith/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightsengineering%2Flocksmith/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/insightsengineering","download_url":"https://codeload.github.com/insightsengineering/locksmith/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightsengineering%2Flocksmith/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262880253,"owners_count":23378760,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T15:10:21.802Z","updated_at":"2025-07-01T01:37:16.660Z","avatar_url":"https://github.com/insightsengineering.png","language":"Go","funding_links":["https://pharmaverse.org"],"categories":[],"sub_categories":[],"readme":"# locksmith\n\n[![build](https://github.com/insightsengineering/locksmith/actions/workflows/test.yml/badge.svg)](https://github.com/insightsengineering/locksmith/actions/workflows/test.yml)\n\n`locksmith` is a utility to generate `renv.lock` file containing all dependencies of given set of R packages.\n\nGiven the input list of git repositories containing the R packages, as well as a list of R package\nrepositories (e.g. in a package manager, CRAN, BioConductor etc.), `locksmith` will try to determine\nthe list of all dependencies and their versions required to make the input list of packages work.\nIt will then save the result in an `renv.lock`-compatible file.\n\nFor additional information about `renv.lock`, please refer to the [`renv` documentation](https://rstudio.github.io/renv/articles/renv.html).\n\n## Installation\n\nSimply download the project for your distribution from the\n[releases](https://github.com/insightsengineering/locksmith/releases) page. `locksmith` is\ndistributed as a single binary file and does not need any additional system requirements.\n\nAlternatively, you can install the latest version by running:\n\n```shell\ngo install github.com/insightsengineering/locksmith@latest\n```\n\n## Usage\n\n`locksmith` is a command line utility, so after installing the binary in your `PATH`, simply run the\nfollowing command to view its capabilities:\n\n```bash\nlocksmith --help\n```\n\nReal-life example with multiple input packages and repositories.\nPlease see below for [an example](#configuration-file) how to set package and repository lists more\neasily in a configuration file.\n\n```bash\nlocksmith --inputPackageList https://raw.githubusercontent.com/insightsengineering/formatters/main/DESCRIPTION,https://raw.githubusercontent.com/insightsengineering/rtables/main/DESCRIPTION,https://raw.githubusercontent.com/insightsengineering/scda/main/DESCRIPTION,https://raw.githubusercontent.com/insightsengineering/scda.2022/main/DESCRIPTION,https://raw.githubusercontent.com/insightsengineering/nestcolor/main/DESCRIPTION,https://raw.githubusercontent.com/insightsengineering/tern/main/DESCRIPTION,https://raw.githubusercontent.com/insightsengineering/rlistings/main/DESCRIPTION,https://gitlab.example.com/api/v4/projects/123456/repository/files/DESCRIPTION/raw?ref=main,https://gitlab.example.com/api/v4/projects/234567/repository/files/directory%2Fsubdirectory%2FDESCRIPTION/raw?ref=main --inputRepositoryList BioC=https://bioconductor.org/packages/release/bioc,CRAN=https://cran.rstudio.com\n```\n\nIn order to download the input `DESCRIPTION` files from GitHub or GitLab repositories, please set the environment\nvariables containing the Personal Access Tokens.\n\n* For GitHub, set the `LOCKSMITH_GITHUBTOKEN` environment variable.\n* For GitLab, set the `LOCKSMITH_GITLABTOKEN` environment variable.\n\nBy default `locksmith` will save the resulting output file to `renv.lock`.\n\n## Configuration file\n\nIf you'd like to set the above options in a configuration file, by default `locksmith` checks\n`~/.locksmith`, `~/.locksmith.yaml` and `~/.locksmith.yml` files.\n\nIf any of these files exist, `locksmith` will use options defined there, unless they are overridden\nby command line flags or environment variables.\n\nYou can also specify custom path to configuration file with `--config \u003cyour-configuration-file\u003e.yml`\ncommand line flag. When using custom configuration file, if you specify command line flags,\nthe latter will still take precedence.\n\nExample contents of configuration file:\n\n```yaml\nlogLevel: debug\ninputPackages:\n  - https://raw.githubusercontent.com/insightsengineering/formatters/main/DESCRIPTION\n  - https://raw.githubusercontent.com/insightsengineering/rtables/main/DESCRIPTION\n  - https://raw.githubusercontent.com/insightsengineering/scda/main/DESCRIPTION\n  - https://raw.githubusercontent.com/insightsengineering/scda.2022/main/DESCRIPTION\n  - https://gitlab.example.com/api/v4/projects/123456/repository/files/DESCRIPTION/raw?ref=main\n  # Forward slashes in 'directory/subdirectory/DESCRIPTION' path are replaced by '%2F' due to URL encoding\n  - https://gitlab.example.com/api/v4/projects/234567/repository/files/directory%2Fsubdirectory%2FDESCRIPTION/raw?ref=main\ninputRepositories:\n  - Bioconductor.BioCsoft=https://bioconductor.org/packages/release/bioc\n  - CRAN=https://cran.rstudio.com\n```\n\nThe example above shows an alternative way of providing input packages, and input repositories,\nas opposed to `inputPackageList` and `inputRepositoryList` CLI flags/YAML keys.\n\nAdditionally, `inputPackageList`/`inputRepositoryList` CLI flags take precendence over\n`inputPackages`/`inputRepositories` YAML keys.\n\nPlease note that package repository URLs should be provided without the trailing `/`.\n\n## Environment variables\n\n`locksmith` reads environment variables with `LOCKSMITH_` prefix and tries to match them with CLI\nflags. For example, setting the following variables will override the respective values from the\nconfiguration file: `LOCKSMITH_LOGLEVEL`, `LOCKSMITH_INPUTPACKAGELIST`, `LOCKSMITH_INPUTREPOSITORYLIST` etc.\n\nThe order of precedence is:\n\nCLI flag → environment variable → configuration file → default value.\n\nTo check the available names of environment variables, please run `locksmith --help`.\n\n## Binary dependencies\n\nIf `locksmith` should generate an `renv.lock` with binary R packages,\nit is necessary to provide URLs to binary repositories via `inputRepositories`/`inputRepositoryList`.\n\nExamples illustrating the expected format of URLs to repositories with binary packages:\n\n* Linux:\n  * `https://packagemanager.posit.co/cran/__linux__/\u003cdistribution-name\u003e/latest`\n* Windows:\n  * `https://cloud.r-project.org/bin/windows/contrib/\u003cr-version\u003e`\n  * `https://www.bioconductor.org/packages/release/bioc/bin/windows/contrib/\u003cr-version\u003e`\n  * `https://packagemanager.posit.co/cran/latest/bin/windows/contrib/\u003cr-version\u003e`\n* macOS:\n  * `https://cloud.r-project.org/bin/macosx/contrib/\u003cr-version\u003e`\n  * `https://www.bioconductor.org/packages/release/bioc/bin/macosx/big-sur-arm64/contrib/\u003cr-version\u003e`\n  * `https://www.bioconductor.org/packages/release/bioc/bin/macosx/big-sur-x86_64/contrib/\u003cr-version\u003e`\n  * `https://packagemanager.posit.co/cran/latest/bin/macosx/big-sur-x86_64/contrib/\u003cr-version\u003e`\n  * `https://packagemanager.posit.co/cran/latest/bin/macosx/big-sur-arm64/contrib/\u003cr-version\u003e`\n\nwhere `\u003cr-version\u003e` is e.g. `4.2`, `4.3` etc.\n\nIn all cases the URL points to a directory where the `PACKAGES` file is located, without the trailing `/`.\n\nAs a result, the configuration file could look like this:\n\n* for macOS:\n\n    ```yaml\n    inputRepositories:\n      - CRAN-macOS=https://cloud.r-project.org/bin/macosx/contrib/4.2\n      - Bioc-macOS=https://www.bioconductor.org/packages/release/bioc/bin/macosx/big-sur-x86_64/contrib/4.3\n    ```\n\n* for Windows:\n\n    ```yaml\n    inputRepositories:\n      - CRAN-Windows=https://cloud.r-project.org/bin/windows/contrib/4.2\n      - Bioc-Windows=https://www.bioconductor.org/packages/release/bioc/bin/windows/contrib/4.3\n    ```\n\n## Packages not found in the repositories\n\nIt may happen that some of the dependencies required by the input packages cannot be found in any of\nthe input repositories. By default, `locksmith` will fail in such case and show a list of such dependencies.\n\nHowever, it is possible to override this behavior by using the `--allowIncompleteRenvLock` flag.\nSimply list the types of dependencies which should not cause the `renv.lock` generation to fail:\n\n```bash\nlocksmith --allowIncompleteRenvLock 'Imports,Depends,Suggests,LinkingTo'\n```\n\n## Updating existing `renv.lock`\n\n`locksmith` has the capability to update an existing lockfile with the newest available package versions.\n\nTo ensure that the `input.renv.lock` has all the packages in the newest versions from the respective repositories (git, CRAN-like or BioConductor-like), and to save such updated file to `output.renv.lock`, you can run:\n\n```bash\nlocksmith --inputRenvLock input.renv.lock --outputRenvLock output.renv.lock\n```\n\nFor git packages, a reference to the latest commit on the default branch will be saved.\n\nFor packages which, according to the input lockfile, should be downloaded from CRAN-like or BioConductor-like repositories, a reference to the latest available package version in the respective repository will be saved.\n\nThe packages can be updated selectively by using the `--updatePackages` flag.\n\nPlease note that `renv` might have saved the information in the input lockfile that a package `P` should be downloaded from `CRAN`, `RSPM` or BioConductor repository, but at the same time the definition of that repository in the `renv.lock` header (in the `Repositories` section) might be missing.\nIn this case, `locksmith` will replicate seemingly undocumented `renv` behavior: the version of package `P` in the lockfile will be updated to the latest version found in any of the repositories **defined** in the lockfile.\n\nPlease also note that `locksmith` will not verify whether the dependencies of some packages have changed - this means that the set of package names present in the lockfile will stay the same.\n\n## Development\n\nThis project is built with the [Go programming language](https://go.dev/).\n\n### Development Environment\n\nIt is recommended to use Go 1.21+ for developing this project. This project uses a pre-commit\nconfiguration and it is recommended to [install and use pre-commit](https://pre-commit.com/#install)\nwhen you are developing this project.\n\n### Common Commands\n\nRun `make help` to list all related targets that will aid local development.\n\n## License\n\n`locksmith` is licensed under the Apache 2.0 license. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsightsengineering%2Flocksmith","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finsightsengineering%2Flocksmith","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsightsengineering%2Flocksmith/lists"}