nickel-scm v0.14.4

Nickel: Keep local repositories in sync

Nickel is a tool to keep a bunch of Git repositories in sync, and to run certain common maintenance operations across those repositories.

Install

npm install -g nickel-scm

Test

nickel --help

This should give the standard help message for nickel.

Configure

Configuration is done using a JS source file with some pre-defined calls available. Nickel will search for this file in the following locations:

1. Wherever the --config command-line argument points
2. ${HOME}/.nickel.js
3. ${HOME}/nickel.js

The Old Way

The content of this file is a series of project declarations. For example:

root = "c:/Dev/Code";
defaultBranch = "develop";
pruneOnFetch = true;

project("project-base");
project("project-commons");
project("project-service");

// All of the "thing" projects share a mark
separator(); // Draw a horizontal line in all reports
project("thing-base", { marks: ["thing"] });
project("thing-commons", { marks: ["thing"] });
project("thing-service", { marks: ["thing"] });

separator("Ops"); // Draw a horizontal line, labeled with the word 'Ops'
defaultBranch = "main";
project("ops-project");

The first line declares where the projects live. If you have projects in multiple locations, root can be changed in the middle of the file and will be picked up by subsequent calls to project(...).

The New Way

projectRoot("c:/Dev", root => {
  root.defaultBranch("develop");
  root.pruneOnFetch(false);

  root.projects("Code", code => {
    code.git("project-base");
    code.git("project-commons");
    code.git("project-service");
  });

  root.projects("thing", thing => {
    thing.separator(true);

    thing.git("thing-base");
    thing.git("thing-commons");
    thing.git("thing-service");
  });

  root.projects("Ops", ops => {
    ops.label("Operations");
    ops.separator(true);
    ops.defaultBranch("main");

    ops.git("ops-project");
  });
});

Run

Here's the standard help message.

Usage: nickel [options] [command]

nickel-scm: Manage local Git repositories

Options:
  -V, --version                   output the version number
  --project <project...>          Select a project by name
  --project-dir <dir...>          Select projects under the indicated folder
  --active-branch <activeBranch>  Select projects with this active branch
  --mark <mark>                   Select projects with this mark
  --config <config>               Configuration file
  --level <level                  Log level (choices: "debug", "info", "warn", "error", default: "info")
  -h, --help                      display help for command

Commands:
  sync                            Sync all projects
  report                          Local repository report (no network interaction)
  cleanup                         Retire unused branches
  mergedReport <reportFile>       Generate a merged branches report
  guidedRemove <reportFile>       Remove branches based on a merged branches report
  oldBranches <reportFile> [age]  Generate a list of branches older than a certain age
  help [command]                  display help for command

The most common form of the command is nickel sync. This will sync all the repositories listed in the config file.

Any list of commands may be listed, though they will be run in a fixed order, rather than in command-line order.

Selecting projects

There are two command-line options that allow you to select the list of projects to run against:

report

Generates a project report. Here's an example:

╔═══════════════════════════╤════════════════════╤═══════╤═════════╤═══════╗
║                   Project │             Branch │ # Mod │  Commit │ Marks ║
╟───────────────────────────┼────────────────────┼───────┼─────────┼───────╢
║    service-project-b-base │ Feature/FOOBAR-456 │     0 │ ca14608 │     a ║
║         project-a-commons │ Feature/FOOBAR-456 │     0 │ 661cc1d │     b ║
║         project-a-service │ Feature/FOOBAR-456 │     0 │ 1a85852 │       ║
║ service-project-b-commons │ Feature/FOOBAR-456 │     0 │ 7f5784a │       ║
║ service-project-b-service │ Feature/FOOBAR-456 │     0 │ 5c5e360 │       ║
╚═══════════════════════════╧════════════════════╧═══════╧═════════╧═══════╝

sync

Sync all projects and report on the results:

╔═══════════════════════════╤════════════════════╤═════════╤══════════════╗
║                   Project │             Branch │ Updated │       Status ║
╟───────────────────────────┼────────────────────┼─────────┼──────────────╢
║    service-project-b-base │ Feature/FOOBAR-456 │       0 │ sync-success ║
║         project-a-commons │ Feature/FOOBAR-456 │       0 │ sync-success ║
║         project-a-service │ Feature/FOOBAR-456 │       2 │ sync-success ║
║ service-project-b-commons │ Feature/FOOBAR-456 │       0 │ sync-success ║
║ service-project-b-service │ Feature/FOOBAR-456 │       0 │ sync-success ║
╚═══════════════════════════╧════════════════════╧═════════╧══════════════╝

Here are the meanings of the status values:

cleanup

Cleanup all projects that are not on their "default" branch:

╔═══════════════════════════╤═════════════════════╤═══════════════╗
║                   Project │              Branch │        Status ║
╟───────────────────────────┼─────────────────────┼───────────────╢
║    service-project-a-base │ Feature/FOOBAR-1111 │ clean-success ║
║ service-project-a-commons │ Feature/FOOBAR-1111 │ clean-success ║
║ service-project-a-service │ Feature/FOOBAR-1111 │ clean-success ║
╟───────────────────────────┼─────────────────────┼───────────────╢
║            prj-client-web │             develop │    clean-skip ║
║   ops-kubernetes-clusters │             develop │    clean-skip ║
║        ops-jenkins-docker │              master │    clean-skip ║
╚═══════════════════════════╧═════════════════════╧═══════════════╝

Here are the meanings of the status values:

mergeReport

Identify merged branches and generate a report.

No example report, in this case, but here are the report columns:

Here are the status values:

guidedRemove

Based on a merge branch report, remove selected branches.

The report structure looks like this:

Here are the status values:

Develop

Some handy commands to run when developing and releasing nickel.

Building Locally

npm run build && npm install -g

Tests

Run unit tests:

npm run test

Run unit tests with coverage:

npm run coverage

Release

npm version patch && npm run build && npm publish