Skip to content
This repository has been archived by the owner on Jul 12, 2022. It is now read-only.

Configuration

Jump to bottom
Anthony Steele edited this page Feb 5, 2019 · 48 revisions

NuKeeper Logo

This page details all commands, command arguments and options in NuKeeper.

In general the syntax is nukeeper <command> command-arguments options. We aim for these to work in a similar way to dotnet.

Command must be one of inspect, update, repo, org, global. if no command is given, help is shown.

Command arguments are specific to each command, and are documented there.

Options are either of the form e.g. --option value or -o value - they have a long name used with a double dash, and might have an equivalent short name used with a single dash. The short name is always a single character, and due to this limitation only some options have a short name.

A value is supplied after a space (or other formats that that library supports). E.g. -a 7d and --age 7d both set the age option to the value 7d. Not every option applies to every command. Options typically do not need to be supplied in every run, they have sensible defaults.

Inspect command

The Inspect command is used to look at files already present on a file system and report possible updates, without any git or server interaction, or changes made locally.

cd  c:\code\MyProject
nukeeper inspect

The path is a command-specific parameter. If not specified, the current folder will be used. e.g.

nukeeper inspect c:\code\MyProject

Update command

The update command is used to look at files already present on a file system and apply an update locally, without any git or server interaction. The path is an optional parameter as in inspect.

nukeeper update c:\code\MyProject

A maximum of one applicable update is applied per run, unless this limit is increased with the --maxupdate option.

nukeeper update c:\code\MyProject --maxupdate 5

Repository command

Github AzureDevOps BitBucket GitLab
✔️ ✔️ ✔️ ❌

The repository command is used to perform version checks and generate pull requests for a single repository. Point it at the https url of a repository, like this:

nukeeper repo <RepoUri> <Token>

Or at the local repository if it's a AzureDevops or VSTS repository:

nukeeper repo . <Token>
nukeeper repo C:/repos/myrepo <Token>

The repository Uri and the token are command-specific required parameters.

The repository does not need to be already present on the machine. It will be fetched over git.

Organisation command

Github AzureDevOps BitBucket GitLab
✔️ ❌ ❌ ❌

The Organisation command is used to perform the checks and generate pull requests for all repositories in the specified organisation that the provided GitToken has access to.

nukeeper org <OrgName> <GitToken>

The organisation name and the git token are required command-specific parameters. The Git token can be omitted if it is found in the environment variables.

Global command

Github AzureDevOps BitBucket GitLab
✔️ ❌ ❌ ❌

The global command is used to apply updates to all repositories on a server. The limitations imposed are that

  • The GitHub API server cannot be the public github.com server, it must be a github enterprise server.
  • An include regex must be specified.
  • Processing stops after maxrepo repositories have Pull Requests raised against them

Environment Variables

Tokens can be provided on the command line or via the following Environment Variables

Name Required? Scopes Help
NuKeeper_github_token Required for GitHub operations repo GitHub
NuKeeper_azure_devops_token Required for Azure DevOps operations code Azure DevOps

The environment variables tmp and temp will control where NuKeeper creates temporary files as per this document, when checking out git repos. You can use this to set a shorter temprary folder path if need be.

If you have just created the environment variables, remember to restart your terminal and IDE before proceeding.

Options

Long name Short name Commands where it applies Default value
help h all
age a all 7d
change c all Major
useprerelease all FromPrerelease
exclude e all null
include i all null
source s all NuGet.org public api url
verbosity v all Normal
logdestination all Console
logfile all 'nukeeper.log'
ouputformat all Text
ouputdestination all Console
ouputfile all 'nukeeper.out'
api g org, global GitHub.com public API Uri
api g repo Depends on repository Uri
fork f repo, org, global PreferFork (Github)
SingleRepository (AzureDevOps)
fork f repo, org, global PreferFork
label l repo, org, global 'nukeeper'
maxpackageupdates m repo, org, global, update 3, or 1 when the command is update
consolidate n repo, org, global false
platform repo, org, global null
maxrepo org, global 10
includerepos org, global null
excluderepos org, global null

  • age The minimum package age. In order to not consume packages immediately after they are released, exclude updates that do not meet a minimum age. The default is 7 days. This age is the duration between the published date of the selected package update and now. A value can be expressed in command options as an integer and a unit suffix, where the unit is one of h for hour, d for days, w for weeks. A zero with no unit is also allowed. Examples: 0 = zero, 12h = 12 hours, 3d = 3 days, 2w = two weeks.

  • change The greatest level of update that is allowed to packages, based on the version number difference. Values are: Major, Minor, Patch. See Semver for what these mean. The default value Major will allow updates to the overall latest version even if it means accepting a new major version.

  • UsePrerelease Should NuKeeper suggest updates to a pre-release (beta) package version. Values are Always, Never, FromPrerelease. The default is FromPrerelease, meaning that only a package that is currently used at a pre-release version will be updated to a later pre-release version.

    For example, if you are currently using package Foo at version 1.2.3 and these new versions are available: 1.2.4 - a patch version change, 1.3.0 - a minor version change and 2.0.0 - a new major version.

    • If the allowed version change is Major (the default) you will get an update to the overall latest version, i.e. 2.0.0.
    • If you set the allowed version change to Minor, you will get an update to 1.3.0 as now changes to the major version number are not allowed. Version 1.2.4 is also allowed, but the largest allowed update is applied.
    • If the allowed version change is Patch you will only get an update to version 1.2.4.

  • exclude Do not consider packages matching this regex pattern.

  • include Only consider packages matching this regex pattern.

  • source Specifies a NuGet package source to use during the operation. This setting overrides all of the sources specified in the NuGet.config files. Multiple sources can be provided by specifying this option multiple times.

  • verbosity. Controls how much log data is produced. Values are, from least output to most output: Quiet, Minimal, Normal, Detailed. Quiet should produce no output unless there is an error, and Detailed is suitable for debugging issues. You can also use short names for these log levels: Q, M, N, D.

  • logdestination: Where log data is sent: One of: Console, File, Off. Default is Console.

  • logfile when set, log data will be appended to the named file instead of going to console.

  • outputformat. Format for output. One of: None, Text, Csv, Metrics,Libyears. Default is Text.

  • outputdestination: Where output is sent: One of: Console, File, Off. Default is Console.

  • outputfilename : Name of file to send output to. Used when output destination is File. default is nukeeper.out.

  • api This is the api endpoint for the instance you're targeting. If you are using an internal server and not a public one, you must set it to the api url for your server. The value will be e.g. https://github.mycompany.com/api/v3.

  • fork Values are PreferFork, PreferSingleRepository and SingleRepositoryOnly. Prefer to make branches on a fork of the target repository, or on that repository itself. See the section "Branches, forks and pull requests" below.

  • label Label to apply to GitHub pull requests. Can be specified multiple times.

  • maxpackageupdates The maximum number of package updates to apply. In repo,org and global commands, this limits the number of updates per repository. If the --consolidate flag is used, these wll be consolidated into one Pull Request. If not, then there will be one Pull Request per update applied. In the update command, The default value is 1. When changed, multiple updates can be applied in a single update run, up to this number.

  • maxrepo The maximum number of repositories to change. Used in Organisation and Global mode.

  • consolidate Consolidate updates into a single pull request, instead of the default of 1 pull request per package update applied.

  • platform One of GitHub, AzureDevOps, Bitbucket, BitbucketLocal. Determines which kind of source control api will be used. This is typicaly infered from the api url structure, but since this does not always work, it can be specified here if neccessary.

  • includerepos A regex to filter repositories by name. Only consider repositories where the name matches this regex pattern. Used in Organisation and Global mode.

  • excluderepos A regex to filter repositories by name. Do not consider repositories where the name matches this regex pattern. Used in Organisation and Global mode.

Output and logging

Text produced by NuKeeper falls into two categories: logging and output. Both can be independently sent to console, or to file, or turned off. Both default to the console.

Options related to logging are verbosity, logdestination and logfile. Options related to output are outputformat, outputdestination, and outputfile

If the run of NuKeeper is intended to produce Pull Requests, then output and logging is less important. But if the run is intended to inspect local code or remote repositories, the output is the primary result of the run. Logging is important for debugging issues.

Logging has verbosity so that it can produce more lines or fewer lines. Verbosity is one of Quiet, Minimal, Normal, Detailed.

Output has different formats, intended for different consumers, be it human or machine-readable.

  • Text is the default format, and is intended to be human readable.
  • None turns it off entirely. No output is produced.
  • Csv produces a report in Comma-Separated Value format, with one line for each package update found.
  • Metrics produces several code metrics, one per line, each with a "name: number" format. The libyears metric is included.
  • libyears outputs only the libyears number.

We may add to the output formats over time based on what people need.

For both logging and output, both destination and file options can be specified on the command-line or in the settings file. The usual fallback applies - values taken are (in order) from command line, from settings file, from the default value.

In both cases, destination is an enumeration, one of Console, File or Off. Off makes a null object that does not record the data at all. File appends to the named file.

In both cases, if the destination is File and no file name is given, then a default file name is used, nukeeper.log for logging, and nukeeper.out for output. So if you specify --logdestination file on the command-line and nothing else log-related, logging will go to the file nukeeper.log.

In both cases, the default destination is Console, unless a file name is given on the command-line, in which case the default is File. So if you specify --outputfile somefile.out on the command-line and nothing else output-related, output will go to the file somefile.out.

Options stored in file

Some options can be stored in a file, in order to make the commandline shorter or re-use values across runs. If a file is found in the current folder with name nukeeper.settings.json then the following settings can be read from file: Age, Api, Change, Consolidate, Exclude, ForkMode, Include, Verbosity, IncludeRepos, ExcludeRepos, Label, LogFile, OutputFormat, OutputDestination, OutputFileName, MaxPackageUpdates, MaxRepo, Platform,UsePrerelease. Keys in the file are not case sensitive. The value for Label should be an array of strings, and other values are either number, bool or string as appropriate.

When a value is present on both commandline and file, command-line values will take precedence over the file values, i.e. the fallback sequence is the first command-line value, then file, then the default.

e.g.

{
  "age": "8d",
  "api": "https://github.contoso.com/api/v3",
  "consolidate": true,
  "exclude": "^Microsoft.AspNetCore",
  "label": [ "automated", "nukeeper" ],
  "MaxPackageUpdates": 10,
  "outputFormat": "Metrics"
}

Branches, forks and pull requests

Nukeeper needs a repository that it can pull a copy of the code from, and a repository that it can push a new branch to. These might or might not be the same repository.

In the most general case, there are two repositories. The standard term for these is upstream and origin, but bear in mind that origin is forked off upstream. origin is the working copy, and the canonical original is upstream. In the NuKeeper code these are sometimes referred to as the "pull fork" and "push fork" respectively, since we pull from the first and push to the second.

There are two possible workflows

Single-repository workflow. The pull fork and push fork are the same repository. NuKeeper will pull from the repository, branch locally, make a change, and push a change back to a branch on the same repository, then PR back to the master branch.

In this workflow, NuKeeper needs permission to push to the target repository.

Fork workflow. The pull fork and push fork are not the same repository. NuKeeper will pull from the upstream, branch locally, make a change, and push it back to a branch on the origin fork, then PR back to the master branch on the upstream.

This workflow can be used if:

  • The user (identified by the GitHub token) already has a repository with the right name, that is a fork of the target repository and we have permission to push there.
  • Or the user does not have a repository with the right name, but it can be created as a fork of the target.

This is automatic, NuKeeper will find the fork, or attempt to create it if it does not exist.

The ForkMode option controls which workflows will be tried, and in what order. Values are PreferFork, PreferSingleRepository and SingleRepositoryOnly.

In PreferFork mode, both workflows will be tried, with the Fork workflow tried first. In PreferSingleRepository mode, both workflows will be tried, with the single-repository workflow tried first. In the SingleRepositoryOnly, only the single-repository workflow will be tried.

If NuKeeper does not find a repository to push to, it will fail to process the upstream repository.

Public open-source projects on github.com that allow PRs from any outside user are very unlikely to allow that outsider to push to the project's repository, and so this case usually uses the fork workflow. Contributing to an open-source project starts with forking the repo to your own GitHub account.

Some organisations use the single-repository workflow, with all team members allowed to push to the shared repository. This is simpler in most ways.

Clone this wiki locally