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 Oct 22, 2018 · 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 e.g. either of the form --option value or -o value - they have a short name used with a single dash, and an equivalent a long name used with a double dash. A value is supplied after a space. 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 GitHub 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 GitHub 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

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 GitHub repository, like this:

nukeeper repo <RepoUri> <GitToken>

The repository Uri and the git 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

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

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

Name Required?
NuKeeper_github_token Required for GitHub operations, unless provided on command line
  • NuKeeper_github_token You will need to create a GitHub personal access token to authorise access to your GitHub server in order to raise pull requests. Be sure to check the "repo" scope when creating the token.

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
exclude e all null
include i all null
source s all NuGet.org public api url
verbosity v all Normal
logfile lf all null
ouputformat om all Text
ouputdestination od all Console
ouputfilename of all 'nukeeper.out'
api g repo, org, global GitHub.com public api url
fork f repo, org, global PreferFork
label l repo, org, global 'nukeeper'
maxpr p repo, org, global 3
report r repo, org, global Off
consolidate co repo, org, global false
maxrepo x org, global 10
maxupdate m update 1
includerepos ir org, global null
excluderepos er 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.

    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.

  • 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 GitHub instance you're targeting. If you are using an internal GitHub server and not the public one, you must set it to the api url for your GitHub 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.

  • maxpr The maximum number of pull requests to raise on any repository. Used in Repository, Organisation and Global modes.

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

  • report Values are Off, On, ReportOnly. This setting controls if a CSV report file of possible updates is generated. The default value Off means that no report is generated. On will generate it and then proceed with the run, ReportOnly is used to generate the report and then exit without making any PRs.

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

  • maxupdate The default value is 1. When changed, multiple updates can be applied in a single update run. If multiple applicable updates are found, up to this number will be applied.

  • 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. Both default to the console.

Options related to outout and logging are verbosity, logfile, outputformat, outputdestination, 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 for what you intend to use the output for.

  • Text is the default format, and is intended to be human readable.
  • None turns it off entirely. No output is produced.
  • Csv produces a Cvs format report with one line for each possible update.
  • 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.

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, Consolidate, Include, Exclude, Verbosity, Change, IncludeRepos, ExcludeRepos, Label, LogFile, OutputFormat, OutputDestination, OutputFileName, MaxPr, MaxRepo. 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",
  "onsolidate": true,
  "exclude": "^Microsoft.AspNetCore",
  "label": [ "automated", "nukeeper" ],
  "maxPr": 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. The default is PreferFork.

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