Command line interface

Please not that this module is under heavy development. Anything described in here may change in future versions. For an up-to-date list of commands and options run atscm --help.

Commands

run [tasks...] - Runs the specified tasks.

If no command is specified when running atscm, this command will be used as the default, e.g. atscm push equals atscm run push. Running atscm --tasks will list all tasks available.
init - Creates a new atscm project.
config - Prints the current project's configuration.
docs - Opens the atscm API documentation in a browser.
update - Checks for atscm updates in the current project and installs a newer version if available. (since atscm-cli version 0.3)

Options (incomplete)

Options available vary on the command used. Run atscm {command} --help for a complete list of options.

--help, -h - Prints usage information.
--version, -v - Prints the current version.
--log-level, -L - Sets the log level.

There are multiple log levels available:
- 0: Silent
- 1: Error
- 2: Warn
- 3: Info (default)
- 4: Debug
Passing -L will only print errors, -LLLL will print debug information.

How to pass options

Options can be passed as regular command line options, e.g. atscm push --cwd ~/Docs or atscm push --cwd=~/Docs, but they can also be passed as environment variables. To do so set environment variables with the uppercase name of the option, prefixed with ATSCM_, e.g. ATSCM_CWD=~/Docs atscm push on a Unix-based machine or by running setx ATSCM_CWD "%USERPROFILE%\Test" under Windows.

Note: Using environment variables to set options requires atscm-cli version >= 0.3.

Overriding project configuration

The project configuration (the Atviseproject module of your project) can also be overridden at runtime.

Passing overrides by using the --project option:

You can pass overrides directly by setting the --project option, where the path to the value to override is delimited with dots (.). E.g. if you want to set the project's opc port to 1234, pass --project.port.opc 1234.

Passing overrides by setting ATSCM_PROJECT environment variables:

Overrides can also be passed as environment variables, prefixed with ATSCM_PROJECT__, where key paths are delimited with a double underscore (__). To set the project's opc port as an example, set the environment variable ATSCM_PROJECT__PORT__OPC to 1234.

Note: Project configuration overrides require atscm-cli version >= 0.3 and atscm version >= 0.4.

Programmatic usage

Please note that using the atscm-cli API is an advanced topic.

It's recommended to use the command line interface whenever possible.

ES6 JavaScript

The code provided in this document is written in ES2015 JavaScript.

You will have to transpile it (e.g with Babel) in order to get it running.

Creating a Cli instance

Basically, the AtSCMCli class can be used just like any other class:

import AtSCMCli from 'atscm-cli';

const cli = new AtSCMCli();

As stated in the API reference the constructor takes any arguments the command line interface can handle. E.g. running

import AtSCMCli from 'atscm-cli';

const cli = new AtSCMCli(['--version']);
cli.launch();

will print the version, just as if we ran the atscm-cli from the command line.

The main difference between API and command line usage is, that exceptions are not handled. You'll have to do that yourself:

import AtSCMCli from 'atscm-cli';

new AtSCMCli(['--version'])
  .launch() // Note: AtSCMCli#launch returns a Promise
  .then(() => console.log('success!'))
  .catch((err) => console.error(`Oops! An error occured: ${err.message}`));

Please refer to AtSCMCli's class reference in order to see all methods and properties available.

Contributing

Contributions are welcome.

Code quality control

All files inside this project are automatically built, linted and tested by CircleCI.

Builds will only pass if they meet the following criteria:

No ESLint errors: We use ESLint to lint our entire JavaScript code. The config used is eslint-config-lsage. Any lint errors will cause the build to fail.
Test coverage >= 90%: We use istanbul to validate test coverage is at least 90 percent. Any commits not covered by tests will cause the build to fail.
Documentation coverage >= 90%: Our source code is documented using ESDoc. We will only merge if your contribution is documented as well.

Setting up the development environment

In order to meet out coding guideline it's very useful to have your development environment set up right.

Linting files

You can lint all source files by running npm run lint. Although most IDEs support running it directly in the editor:

Jetbrains Webstorm

Webstorm has built-in support for ESLint. Check out their documentation to set it up.

Atom

Atom has several packages that provide support for inline ESLint validation. We recommend you to use linter-eslint.

Running tests

Our mocha tests can be run by calling npm test. If you want the tests to be run right after you saved your changes, then run npm run test:watch.

Test coverage can be checked by running npm run test:coverage.

Creating API documentation

Run npm run docs to create ESDoc API documentation.

Providing fixes / adding features

Take the following steps:

Create a new branch / fork of the beta branch, which is our development branch
Make your changes
Make sure CI tests pass
Send a pull request to merge back to beta

Once we reviewed your changes, we'll merge your pull request.

Merge strategy (Maintainers only)
Accepted changes from fix/feature branches should always be squash-merged to beta.

Once beta is stable create a regular merge commit to merge back to master.
After merging to master, changes should be synced back to the beta branch. To do so, run:
git checkout beta
git fetch
git rebase origin/master
# Solve conflicts if any, accepting changes from master
git commit -m 'chore: Update from master'
git push