Nift Commands

Available Nift commands

Nift Tassie devil mascot

Nift has a number of commands you can use that will help you manage and generate your projects and websites. This page outlines how to list all the available commands and outlines what most of them do.

To use a command, enter nsm command parameter-1 ... parameter-n in to a terminal, command prompt or power shell window.

[contents]

The following have commands available with Nift that are documented on this page:

Listing available Nift commands

To list available Nift commands run nsm commands. The list will look similar to:

+--------- available commands ------------------------------------------+
| commands          | lists all Nift commands                           |
| config            | list or set Git email/username                    |
| clone             | input: clone-url                                  |
| diff              | input: file-path                                  |
| pull              | pull remote changes locally                       |
| bcp               | input: commit-message                             |
| init              | start managing a project - input: output-ext      |
| init-html         | start managing html website - input: (site-name)  |
| status            | lists updated and problem files                   |
| info              | input: name-1 .. name-k                           |
| info-all          | lists watched directories and tracked files       |
| info-config       | lists config settings                             |
| info-names        | lists tracked names                               |
| info-tracking     | lists tracked files                               |
| info-watching     | lists watched directories                         |
| track             | input: name (title) (template-path)               |
| track-from-file   | input: file-path                                  |
| track-dir         | input: dir-path (cont-ext) (temp-path) (out-ext)  |
| untrack           | input: name                                       |
| untrack-from-file | input: file-path                                  |
| untrack-dir       | input: dir-path (content-ext)                     |
| rm or del         | input: name                                       |
| rm-from-file      | input: file-path                                  |
| rm-dir            | input: dir-path (content-ext)                     |
| mv or move        | input: old-name new-name                          |
| cp or copy        | input: tracked-name new-name                      |
| build-names       | input: name-1 .. name-k                           |
| build-updated     | builds updated output files                       |
| build-all         | builds all tracked output files                   |
| serve             | serves project locally                            |
| new-title         | input: name new-title                             |
| new-template      | input: (name) template-path                       |
| new-output-dir    | input: dir-path                                   |
| new-cont-dir      | input: dir-path                                   |
| new-cont-ext      | input: (name) content-extension                   |
| new-output-ext    | input: (name) output-extension                    |
| new-script-ext    | input: (name) script-extension                    |
| no-build-thrds    | input: (no-threads) [-n == n*cores]               |
| backup-scripts    | input: (option)                                   |
| watch             | input: dir-path (cont-ext) (temp-path) (out-ext)  |
| unwatch           | input: dir-path (cont-ext)                        |
+-----------------------------------------------------------------------+

Initialise managing a project or website

To start managing a project: first change to the directory you would like to act as the project root directory, that is the directory containing all project related files (content and template files inclusive); then run nsm init output-extension where output-extension is a parameter for the default output extension used when building files. A hidden directory .nsm will be created containing a tracking.list file and config file nift.config.

To start managing a website: first change to the directory you would like to act as the project root directory, that is the directory containing all site related files (content and template files inclusive); then run nsm init (site-name) where site-name is an optional parameter for the name of the site. A hidden directory .nsm will be created containing a tracking.list file and config file nift.config.

Note: once the project root directory for your project is set up, much the same as with Git, Nift may be run from any directory within the project root directory (project root directory inclusive).

Listing and setting Git username/email

Especially is you are installing through Snap where its own version of Git needs to be installed, you can list the configured username and email for Git with nsm config --global user.name and nsm config --global user.email. Further you can add a username/email address after either of the commands to set the username or password.

Importing/forking, renaming and cloning a project repository from BitBucket/GitHub/GitLab

You can import/fork and rename an existing project repository on BitBucket, GitHub or GitLab, then clone it using nsm clone repository-url. Note - You can rename a repository when importing it, rather than forking and renaming, plus on BitBucket and GitHub you cannot remove fork relationships. Also to host a website on GitHub you will need to go in to the website repository's settings, find the GitHub Pages section and set the source branch (typically master branch).

Diff of file since last commit

If your project directory is a Git repository you can get the diff of a file using nsm diff file-path where file-path is the path from the project root directory to the file you want the diff of.

Pulling remote changes locally

If your project root directory is a Git repository you can pull remote changes locally using nsm pull

Building, committing and pushing changes to BitBucket/GitHub/GitLab

If your project is part of a repository for BitBucket, GitHub or GitLab you can have updated files built along with the changes being committed and pushed using nsm bcp "commit message".

Listing files that need building

For information on files that need building and why run nsm status.

Tracking files

The easiest way to track a new file is with nsm track name title template-path, where title and template-path are optional (default title is the specified name, and default template-path is the site-wide template path specified in the site configuration file). Surround any titles and/or paths containg spaces with single or double quotes. If you want both spaces and single/double quotes in your title/path then surround it by double/single quotes.

The following work as valid names titles:

index
'about page'
docs/installing
"path with spaces/filename"
home
'home'
"home page"
"John's page"

Note: you should not do any of the following with names, titles or paths:

  • use tabs;
  • use consecutive spaces;
  • use both single and double quotes;
  • single and double quote the entire string, eg. '"bad idea"'.
Also names cannot contain fullstops. If you desperately need the output file to contain fullstops other than in the extension then use a post-build script to move or copy the built file.

With websites you can either put asset files like css and javascript files straight in the output/website directory and modify them from there, or you can track them similar to your pages and use Nift's template language when coding them as well.

Note: When you track a file, the content file path is @[contentdir]/@[name]@[contentext] and the output file path is @[outputdir]/@[name]@[outputext]. For example, if you have content directory content/, content extension .content, output directory site/ and output extension .html and you track about, then the content file will be located at content/about.content and the output file will be built to site/about.html.

To track all files in a specified directory with a specified content extension you can use:

nsm track-dir dir-path (content-extension) (template-path) (output-extension)
where:
  • dir-path is the directory you want to track files from;
  • content-extension is the content extension to check for, if not specified the project-wide content extension is used;
  • template-path is the template path to track with, if not specified the project-wide default template path is used;
  • output-extension is the output extension to track with, if not specified the project-wide output extension is used.

Another way to track large volumes of files is from a file using:

nsm track-from-file file-path

The file specifying files to track should have one file specified on each line with the format:

name (title) (content-extension) (template-path) (output-extension)
where:
  • name is the name of the file you want to track;
  • title is the title, if not specified the name is used;
  • content-ext is the content extension to use, if not specified the project-wide content extension is used;
  • template-path is the template path to track with, if not specified the project-wide default template path is used;
  • output-ext is the output extension to track with, if not specified the project-wide output extension is used.

Note: the file with files to track can have empty lines and comment lines beginning with '#' and you should quote any names, titles, extensions or paths containing spaces.

Listing information about the project

To list information about the project configuration run nsm info-config, for all watched directories and tracked files run nsm info-all, for just tracked files run nsm info-tracking, for just watched directories run nsm info-watching, for just names run nsm info-names and for information on specific files run nsm info name-1 .. name-k.

Untracking tracked files

To untrack a file run nsm untrack name. All information about the file is removed from .nsm/tracking.list along with the output file and the info file. It is up to you whether you want to manually remove any associated content and/or template files (or alternatively use rm/del).

To untrack all tracked files in a specified directory with a specified content extension you can use:

nsm untrack-dir dir-path (content-extension)
where:
  • dir-path is the directory you want to untrack files from;
  • content-extension is the content extension to check for, if not specified the project-wide content extension is used.

Another way to untrack large volumes of files is from a file using:

nsm untrack-from-file file-path

The file specifying tracked files to untrack should have one tracked file specified on each line with the format:

name
where:
  • name is the name of the file you want to track.

Note: the file with files to untrack can have empty lines and comment lines beginning with '#' and you should quote any names containing spaces. Also everything after the name on each line is ignored, so you can use the same file used to track the files to untrack them again.

Moving tracked files

To move a tracked file run nsm mv old-name new-name. All information about old-name is removed from .nsm/tracking.list along with the old output file and the old info file, while information about the new file is added to .nsm/tracking.list and the old content file is moved to the new content path.

Copying tracked files

To copy a tracked file run nsm cp tracked-name new-name. Information about new-name is added to .nsm/tracking.list and the old content file is copied to the new content path.

Removing tracked files

To remove a tracked file run nsm rm name. The only difference to untrack is that the content file will also be removed from your system.

To remove all tracked files in a specified directory with a specified content extension you can use either of the following:

nsm rm-dir dir-path (content-extension)
nsm del-dir dir-path (content-extension)
where:
  • dir-path is the directory you want to remove files from;
  • content-extension is the content extension to check for, if not specified the project-wide content extension is used.

Another way to remove large volumes of tracked files is from a file using either of the following:

nsm rm-from-file file-path
nsm del-from-file file-path

The file specifying tracked files to remove should have one tracked file specified on each line with the format:

name
where:
  • name is the name of the tracked file you want to remove.

Note: the file with tracked file to remove can have empty lines and comment lines beginning with '#' and you should quote any names containing spaces. Also everything after the name on each line is ignored, so you can use the same file used to track the files to remove them again.

Watching directories

If you want to automatically track and untrack files based on the existence of content files in a specified directory you can do so by watching directories. To watch a specified directory with a specified content extension you can use:

nsm watch dir-path (content-extension) (template-path) (output-extension)
where:
  • dir-path is the directory you want to watch files from;
  • content-extension is the content extension to check for, if not specified the project-wide content extension is used;
  • template-path is the template path to track files with, if not specified the project-wide default template path is used;
  • output-extension is the output extension to track files with, if not specified the project-wide output extension is used.

When a build is run, any new files in a watched directory with the specified content extension will be tracked and built, and any files where the content file has been removed will be untracked.

Note: you can watch the same directory multiple times with different content extensions, and subdirectories are not included you must watch them separately.

Unwatching directories

To unwatch a specified directory with a specified content extension you can use:

nsm unwatch dir-path (content-extension)
where:
  • dir-path is the directory you want to stop watching files from;
  • content-extension is the content extension to stop watching files from, if not specified the site-wide content extension is used.

Building output files

To build updated output files run nsm build-updated, to build all output files run nsm build-all, and to build specific files run nsm build-names name-1 .. name-k.

Serving your project locally

To serve a project locally run nsm serve, enter exit to stop serving your website. Nift will repeatedly run build-updated then sleep for 500ms (0.5s), if you want Nift to sleep for a different amount of time you can use nsm serve sleep-ms. If your updates are not appearing upon refresh or reload of the output file there's a chance the builds are failing, try checking the .serve-build-log.txt file in the project root directory.

On linux you can also run nsm serve -s & to serve in the background then to stop serving run killall nsm. Then you can open the webpages/output files in the output directory and Nift will automatically build the project in the background, picking up any changes, just reload your browser window or reload the output file in your editor (often they will pop up a dialogue saying the file has been changed and asking whether you would like to reload).

If you would like your website to be served at an IP address, eg. if you are using Nift on a server or a virtual machine, try using Python (there are also options available through npm). Run either of the following in the project root directory for a url similar to 0.0.0.0:8000/site and from the site directory for a url similar to 0.0.0.0:8000.

python3 -m http.server 8000
python -m SimpleHTTPServer

If you want live reloading for a website check out Live Server which you can get from npm, or Live Reload. In either case you can add them to pre/post serve scripts for your website so that it is all integrated in to the Nift serve command and requires no manual effort on your part.

Changing a title

To set a new title run nsm new-title name new-title.

Changing template path

To set a new template path run nsm (name) new-template-path.

Changing output directory

To move the output directory run nsm new-output-dir directory-path.

Changing content directory

To move the content directory run nsm new-cont-dir directory-path.

Changing content extension

To set a new content extension run nsm new-cont-ext (name) content-extension.

Changing output extension

To set a new output extension run nsm new-output-ext (name) extension.

Changing script extension

To set a new script extension run nsm new-script-ext (name) script-extension.

Note: You may set the extension to the empty string "" for pre/post build/serve programs on unix (just set it to .exe on Windows).

Checking and setting number of build threads

You can check the number of build threads with nsm no-build-thrds or nsm info-config and set the number of build threads with nsm no-build-thrds no-threads.

Note: -n build threads represents using n times the number of cores on the machine threads when building projects.

Checking and setting whether to backup scripts

You can check whether scripts will be backed up with nsm backup-scripts or nsm info-config and set whether to backup scripts with nsm backup-scripts option, where to not back up you can use option = 0 and to backup you can use option = 1.

What information is tracked for a file?

While Nift is easiest to learn and understand by using, users may find it useful to remember that for each tracked file Nift tracks a name, title, template path, content extension, output extension and script extension. In more detail, a list of tracked files is stored in the file .nam/tracking.list from where Nift is initialised. When building an output file, say with name index, an info file is created that stores information about file dependencies.

What is a file dependency?

Anything that when modified requires an output file to be rubuilt, including:
  • changes to some information about a tracked file; and
  • modifications to content files and/or template files.

Note: the modification/removal of an output file is intentionally not considered a dependency. This is so that, should the user want to, output files may be moved (not just copied) outside the project without Nift thinking the output files need to be built when in fact they do not (though this is not really recommended, better to just copy the files elsewhere).

How does Nift track modifications to file dependencies?

The information stored in an information file for a tracked file represents the information from the last time the output file was built. If the information file does not exist, as far as Nift is concerned the file has never been built. It will compare both: the information from the info file against the information in .nsm/tracking.list; and whether any of the content and/or template files have been modified since the info file was modified, and hence since the output file was last built.

While Nift will not directly pick up the existence of new content/template files that are merely added via other content/template files, in order for this to occur a content file which is already recorded as a file dependency must be modified, resulting in Nift picking up the new file(s) indirectly. Consequently Nift will inform the user that any relevant output files require building, and upon the user building (updated) files any new content files will also be recorded as file dependencies.

User-defined file dependencies

You can add file dependencies manually by adding a .deps file residing in the same directory as the content file for the file. For example if you have content/index.content as the content file add a content/index.deps file containing the extra dependencies you want to track.

File dependencies may also be added using the @dep(dep-path) syntax in Nift's template language, which you can read more about on the content files page of the documentation.