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 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.

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 config settings or set git email/username  |
| clone          | input: clone-url                                |
| diff           | input: file-path                                |
| pull           | pull remote changes locally                     |
| init           | initialise managing a site - input: (site-name) |
| status         | lists updated and problem pages                 |
| info           | input: page-name-1 .. page-name-k               |
| info-all       | lists tracked pages                             |
| info-names     | lists tracked page names                        |
| track          | input: page-name (page-title) (template-path)   |
| untrack        | input: page-name                                |
| rm or del      | input: page-name                                |
| mv or move     | input: old-name new-name                        |
| cp or copy     | input: tracked-name new-name                    |
| build          | input: page-name-1 .. page-name-k               |
| build-updated  | builds updated pages                            |
| build-all      | builds all tracked pages                        |
| serve          | serves website locally                          |
| bcp            | input: commit-message                           |
| new-title      | input: page-name new-title                      |
| new-template   | input: (page-name) template-path                |
| new-site-dir   | input: dir-path                                 |
| new-cont-dir   | input: dir-path                                 |
| new-cont-ext   | input: (page-name) content-extension            |
| new-page-ext   | input: (page-name) page-extension               |
| new-script-ext | input: (page-name) script-extension             |
| no-build-thrds | input: (no-threads) [-n == n*cores]             |

Importing/Forking, renaming and cloning a site repository from BitBucket/GitHub/GitLab

You can import/fork and rename an existing site 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 on GitHub you will need to go in to the site 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 directory is a Git repository you can pull remote changes locally using nsm pull

Initialise managing a site

To start managing a site: first change to the directory you would like to act as the site stage, 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 .siteinfo will be created containing a pages.list file and config file nsm.config.

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

Listing updated pages

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

Tracking new pages

To track a new page run nsm track page-name page-title template-path, where page-title and template-path are optional (default page-title is the specified page-name, and default template-path is template/page.template). 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 should (hopefully) work as valid titles and paths (though if you are going to use spaces/quotes in titles/paths, test it thoroughly before depending on it working):

"home page"
"nick's page"
'"quoted title"'
'content/index page.content'

Note: tabs and multiple spaces will currently be morphed into single spaces. If the available options for titles/paths are not flexible enough then ask and I can alter how titles/paths are read.

Listing tracked pages

To list information on all pages run nsm info-all, for just page names run nsm info-names, and for information on specific pages run nsm info page-name-1 .. page-name-k.

Untracking pages

To untrack a page run nsm untrack page-name. All information about the page is removed from .siteinfo/pages.list along with the page file and the page info file. It is up to you whether you want to manually remove any associated content and/or template files.

Moving pages

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

Copying pages

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

Removing pages

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

Building pages

To build updated pages run nsm build-updated, to build all pages run nsm build-all, and to build specific pages run nsm build page-name-1 .. page-name-k.

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

If your site is part of a repository for BitBucket, GitHub or GitLab you can have updated pages built along with the changes being committed and pushed using nsm bcp "commit message". Note you can still use nsm build-updated to check any changes locally (when changes can be viewed locally).

Serving Your Website Locally

To serve your website 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 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 in the site directory and Nift will automatically build the website in the background, picking up any changes, just reload your browser window.

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. Run either of the following in the project root directory for a url similar to and from the site directory for a url similar to

python3 -m http.server 8000
python -m SimpleHTTPServer

If you want live reloading 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 page title or template path

To set a new page title run nsm new-title page-name new-title and to set a new template path run nsm (page-name) new-template-path.

Changing site directory

To set a new site directory run nsm new-site-dir directory-path.

Changing content directory

To set a new content directory run nsm new-cont-dir directory-path.

Changing content extension

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

Changing page extension

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

Changing script extension

To set a new script extension run nsm new-script-ext (page-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 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 websites.

What information is tracked for a page?

While Nift is easiest to learn and understand by using, users may find it useful to remember that for each page Nift tracks a page name, page title and template path. In more detail, a list of pages is stored in the file .siteinfo/pages.list from where Nift is initialised. When building a page, say index, a page info file is created that stores information about page dependencies.

What is a page dependency?

Anything that when modified requires a page to be built, including:
  • changes to information about a tracked page; and
  • modifications to content files and/or template files.

Note: the modification/removal of a page file is intentionally not considered a page dependency. This is so that, should the user want to, pages may be moved (not just copied) outside the stage directory without Nift thinking the pages need to be built when in fact they do not.

How does Nift track modifications to page dependencies?

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

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

User-defined page dependencies

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

Page 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.