How to use the clipanion.Command.Usage function in clipanion

To help you get started, we’ve selected a few clipanion examples, based on popular ways it is used in public projects.

Secure your code as it's written. Use Snyk Code to scan source code in minutes - no build needed - and fix issues immediately.

github yarnpkg / berry / packages / plugin-essentials / sources / commands / set / version.ts View on Github external
const BUNDLE_REGEXP = /^yarn-[0-9]+\.[0-9]+\.[0-9]+\.js$/;
const BERRY_RANGES = new Set([`berry`, `nightly`, `nightlies`, `rc`]);

// eslint-disable-next-line arca/no-default-export
export default class SetVersionCommand extends BaseCommand {
  @Command.String()
  range!: string;

  @Command.Boolean(`--allow-rc`)
  includePrereleases: boolean = false;

  @Command.Boolean(`--dry-run`)
  dryRun: boolean = false;

  static usage = Command.Usage({
    description: `lock the Yarn version used by the project`,
    details: `
      This command will download a specific release of Yarn directly from the Yarn Github repository, will store it inside your project, and will change the \`yarnPath\` settings from your project \`.yarnrc.yml\` file to point to the new file.

      A very good use case for this command is to enforce the version of Yarn used by the any single member of your team inside a same project - by doing this you ensure that you have control on Yarn upgrades and downgrades (including on your deployment servers), and get rid of most of the headaches related to someone using a slightly different version and getting a different behavior than you.

      The command will by default only consider stable releases as valid candidates, but releases candidates can be downloaded as well provided you add the \`--allow-rc\` flag or use an exact tag.

      Note that because you're on the v2 alpha trunk, running the command without parameter will always download the latest build straight from the repository. This behavior will be tweaked near the release to only download stable releases once more.

      Adding the \`--dry-run\` flag will cause Yarn not to persist the changes on the disk.
    `,
    examples: [[
      `Download the latest release from the Yarn repository`,
      `$0 set version latest`,
    ], [
github yarnpkg / berry / packages / yarnpkg-builder / sources / commands / new / plugin.ts View on Github external
import {Filename, npath, ppath, xfs} from '@yarnpkg/fslib';
import chalk                         from 'chalk';
import {Command, UsageError}         from 'clipanion';
import path                          from 'path';

// eslint-disable-next-line arca/no-default-export
export default class NewPluginCommand extends Command {
  @Command.String()
  target!: string;

  static usage = Command.Usage({
    description: `generate the template for a new plugin`,
  });

  @Command.Path(`new`, `plugin`)
  async execute() {
    const target = npath.toPortablePath(path.resolve(this.target));
    if (await xfs.existsPromise(target)) {
      const listing = await xfs.readdirPromise(target);
      if (listing.length !== 0) {
        throw new UsageError(`The target directory (${this.target}) isn't empty; aborting the scaffolding.`);
      }
    }

    await xfs.mkdirpPromise(target);
    await xfs.mkdirpPromise(ppath.join(target, `sources` as Filename));
github yarnpkg / berry / packages / plugin-workspace-tools / sources / commands / workspace.ts View on Github external
import {CommandContext, Configuration, Project, Workspace} from "@yarnpkg/core";
import {structUtils}                                       from "@yarnpkg/core";
import {Command, UsageError}                               from "clipanion";

// eslint-disable-next-line arca/no-default-export
export default class WorkspaceCommand extends Command<CommandContext> {
  @Command.String()
  workspaceName!: string;

  @Command.String()
  commandName!: string;

  @Command.Proxy()
  args: Array<string> = [];

  static usage = Command.Usage({
    category: `Workspace-related commands`,
    description: `run a command within the specified workspace`,
    details: `
      > In order to use this command you need to add \`@yarnpkg/plugin-workspace-tools\` to your plugins.

      This command will run a given sub-command on a single workspace.
    `,
    examples: [[
      `Add a package to a single workspace`,
      `yarn workspace components add -D react`,
    ], [
      `Run build script on a single workspace`,
      `yarn workspace components run build`,
    ]],
  });
github yarnpkg / berry / packages / plugin-essentials / sources / commands / node.ts View on Github external
import {BaseCommand}            from '@yarnpkg/cli';
import {Configuration, Project} from '@yarnpkg/core';
import {execUtils, scriptUtils} from '@yarnpkg/core';
import {Command}                from 'clipanion';

// eslint-disable-next-line arca/no-default-export
export default class NodeCommand extends BaseCommand {
  @Command.Proxy()
  args: Array<string> = [];

  static usage = Command.Usage({
    description: `run node with the hook already setup`,
    details: `
      This command simply runs Node. It also makes sure to call it in a way that's compatible with the current project (for example, on PnP projects the environment will be setup in such a way that PnP will be correctly injected into the environment).

      The Node process will use the exact same version of Node as the one used to run Yarn itself, which might be a good way to ensure that your commands always use a consistent Node version.
    `,
    examples: [[
      `Run a Node script`,
      `$0 node ./my-script.js`,
    ]],
  });

  @Command.Path(`node`)
  async execute() {
    const configuration = await Configuration.find(this.context.cwd, this.context.plugins);
    const {project} = await Project.find(configuration, this.context.cwd);
github yarnpkg / berry / packages / plugin-version / sources / commands / version / apply.ts View on Github external
// Basically we only support auto-upgrading the ranges that are very simple (^x.y.z, ~x.y.z, >=x.y.z, and of course x.y.z)
const SUPPORTED_UPGRADE_REGEXP = /^(>=|[~^]|)^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-(0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(\.(0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*)?(\+[0-9a-zA-Z-]+(\.[0-9a-zA-Z-]+)*)?$/;

// eslint-disable-next-line arca/no-default-export
export default class VersionApplyCommand extends BaseCommand {
  @Command.Boolean(`--all`)
  all: boolean = false;

  @Command.Boolean(`--json`)
  json: boolean = false;

  @Command.Boolean(`--dependents`)
  dependents: boolean = false;

  static usage = Command.Usage({
    category: `Release-related commands`,
    description: `apply all the deferred version bumps at once`,
    details: `
      This command will apply the deferred version changes (scheduled via \`yarn version major|minor|patch\`) on the current workspace (or all of them if \`--all\`) is specified.

      It will also update the \`workspace:\` references across all your local workspaces so that they keep refering to the same workspace even after the version bump.

      If the \`--json\` flag is set the output will follow a JSON-stream output also known as NDJSON (https://github.com/ndjson/ndjson-spec).
    `,
    examples: [[
      `Apply the version change to the local workspace`,
      `yarn version apply`,
    ], [
      `Apply the version change to all the workspaces in the local workspace`,
      `yarn version apply --all`,
    ]],
github yarnpkg / berry / packages / plugin-version / sources / commands / version / check.ts View on Github external
import {WorkspaceRequiredError}                                                                                         from '@yarnpkg/cli';
import {CommandContext, Configuration, MessageName, Project, StreamReport, Workspace, execUtils, structUtils, Manifest} from '@yarnpkg/core';
import {Filename, PortablePath, fromPortablePath, ppath, toPortablePath, xfs}                                           from '@yarnpkg/fslib';
import {Command, UsageError}                                                                                            from 'clipanion';

// eslint-disable-next-line arca/no-default-export
export default class VersionApplyCommand extends Command<CommandContext> {
  static usage = Command.Usage({
    category: `Release-related commands`,
    description: `check that all the relevant packages have been bumped`,
    details: `
      **Warning:** This command currently requires Git.

      This command will check that all the packages covered by the files listed in argument have been properly bumped or declined to bump.

      In the case of a bump, the check will also cover transitive packages - meaning that should \`Foo\` be bumped, a package \`Bar\` depending on \`Foo\` will require a decision as to whether \`Bar\` will need to be bumped. This check doesn't cross packages that have declined to bump.

      In case no arguments are passed to the function, the list of modified files will be generated by comparing the HEAD against \`master\`.
    `,
    examples: [[
      `Check whether the modified packages need a bump`,
      `yarn version check`,
    ]],
  });
github yarnpkg / berry / packages / plugin-essentials / sources / commands / remove.ts View on Github external
import {StreamReport, Workspace}                   from '@berry/core';
import {structUtils}                               from '@berry/core';
import {Command, UsageError}                       from 'clipanion';

import * as suggestUtils                           from '../suggestUtils';
import {Hooks}                                     from '..';

// eslint-disable-next-line arca/no-default-export
export default class RemoveCommand extends BaseCommand {
  @Command.Boolean(`-A,--all`)
  all: boolean = false;

  @Command.Rest()
  names: Array<string> = [];

  static usage = Command.Usage({
    description: `remove dependencies from the project`,
    details: `
      This command will remove the specified packages from the current workspace.

      If the \`-A,--all\` option is set, the operation will be applied to all workspaces from the current project.
    `,
    examples: [[
      `Remove a dependency from the current project`,
      `yarn remove lodash`,
    ], [
      `Remove a dependency from all workspaces at once`,
      `yarn remove lodash --all`,
    ]],
  });

  @Command.Path(`remove`)
github yarnpkg / berry / packages / plugin-essentials / sources / commands / set / version / sources.ts View on Github external
@Command.String(`--path`)
  installPath?: string;

  @Command.String(`--repository`)
  repository: string = `https://github.com/yarnpkg/berry.git`;

  @Command.String(`--branch`)
  branch: string = `master`;

  @Command.Array(`--plugin`)
  plugins: Array<string> = [];

  @Command.Boolean(`-f,--force`)
  force: boolean = false;

  static usage = Command.Usage({
    description: `build Yarn from master`,
    details: `
      This command will clone the Yarn repository into a temporary folder, then build it. The resulting bundle will then be copied into the local project.
    `,
    examples: [[
      `Build Yarn from master`,
      `$0 set version from sources`,
    ]],
  });

  @Command.Path(`set`, `version`, `from`, `sources`)
  async execute() {
    const configuration = await Configuration.find(this.context.cwd, this.context.plugins);
    const {project, workspace} = await Project.find(configuration, this.context.cwd);

    if (!workspace)
github yarnpkg / berry / packages / plugin-workspace-tools / sources / commands / foreach.ts View on Github external
@Command.Array(`--exclude`)
  exclude: Array<string> = [];

  @Command.Boolean(`--private`)
  private: boolean = true;

  static schema = yup.object().shape({
    jobs: yup.number().min(2),
    parallel: yup.boolean().when(`jobs`, {
      is: (val: number) => val > 1,
      then: yup.boolean().oneOf([true], `--parallel must be set when using --jobs`),
      otherwise: yup.boolean(),
    }),
  });

  static usage = Command.Usage({
    category: `Workspace-related commands`,
    description: `run a command on all workspaces`,
    details: `
      > In order to use this command you need to add \`@yarnpkg/plugin-workspace-tools\` to your plugins.

      This command will run a given sub-command on all child workspaces that define it (any workspace that doesn't define it will be just skiped). Various flags can alter the exact behavior of the command:

      - If \`-p,--parallel\` is set, the commands will run in parallel; they'll by default be limited to a number of parallel tasks roughly equal to half your core number, but that can be overriden via \`-j,--jobs\`.

      - If \`-p,--parallel\` and \`-i,--interlaced\` are both set, Yarn will print the lines from the output as it receives them. If \`-i,--interlaced\` wasn't set, it would instead buffer the output from each process and print the resulting buffers only after their source processes have exited.

      - If \`-t,--topological\` is set, Yarn will only run a command after all workspaces that depend on it through the \`dependencies\` field have successfully finished executing. If \`--tological-dev\` is set, both the \`dependencies\` and \`devDependencies\` fields will be considered when figuring out the wait points.

      - If \`--all\` is set, Yarn will run it on all the workspaces of a project. By default it runs the command only on child workspaces.

      - The command may apply to only some workspaces through the use of \`--include\` which acts as a whitelist. The \`--exclude\` flag will do the opposite and will be a list of packages that musn't execute the script.
github yarnpkg / berry / packages / plugin-essentials / sources / commands / add.ts View on Github external
@Command.Boolean(`-D,--dev`)
  dev: boolean = false;

  @Command.Boolean(`-P,--peer`)
  peer: boolean = false;

  @Command.Boolean(`--prefer-dev`)
  preferDev: boolean = false;

  @Command.Boolean(`-i,--interactive`)
  interactive: boolean = false;

  @Command.Boolean(`--cached`)
  cached: boolean = false;

  static usage = Command.Usage({
    description: `add dependencies to the project`,
    details: `
      This command adds a package to the package.json for the nearest workspace.

      - If it didn't exist before, the package will by default be added to the regular \`dependencies\` field, but this behavior can be overriden thanks to the \`-D,--dev\` flag (which will cause the dependency to be added to the \`devDependencies\` field instead) and the \`-P,--peer\` flag (which will do the same but for \`peerDependencies\`).

      - If the package was already listed in your dependencies, it will by default be upgraded whether it's part of your \`dependencies\` or \`devDependencies\` (it won't ever update \`peerDependencies\`, though).

      - If set, the \`--prefer-dev\` flag will operate as a more flexible \`-D,--dev\` in that it will add the package to your \`devDependencies\` if it isn't already listed in either \`dependencies\` or \`devDependencies\`, but it will also happily upgrade your \`dependencies\` if that's what you already use (whereas \`-D,--dev\` would throw an exception).

      - If the added package doesn't specify a range at all its \`latest\` tag will be resolved and the returned version will be used to generate a new semver range (using the \`^\` modifier by default, or the \`~\` modifier if \`-T,--tilde\` is specified, or no modifier at all if \`-E,--exact\` is specified). Two exceptions to this rule: the first one is that if the package is a workspace then its local version will be used, and the second one is that if you use \`-P,--peer\` the default range will be \`*\` and won't be resolved at all.

      - If the added package specifies a tag range (such as \`latest\` or \`rc\`), Yarn will resolve this tag to a semver version and use that in the resulting package.json entry (meaning that \`yarn add foo@latest\` will have exactly the same effect as \`yarn add foo\`).

      If the \`--cached\` option is used, Yarn will preferably reuse the highest version already used somewhere within the project, even if through a transitive dependency.