cmd: incr-mode
[contents]

Contents

Syntax

The syntax for the incr-mode command is: 

nift incr-mode (mode)
nsm incr-mode (mode)

Description

The incr-mode command is for getting and setting the mode to use for incremental builds and checking the status of a project, it either takes zero parameters and returns the incremental mode being used for the current project, or it takes a string parameter to specify which mode to set. There are a number of modes available outlined in the following section.

Modes

The following options are available for incr-mode calls:

mode description
mod use file modification times to determine which files have been updated
hash use file hashes to determine which files have been updated
hybrid use both file modification times and file hashes to determine which files have been updated
mode description

Note: mod mode is fastest and will have a slightly smaller project size, however if you need to copy the entire project to another machine/server and have the build-updated and status commands still work then you need to use either the hash or hybrid modes. If you can use something like Git to push changes from a development machine/server to another machine which also uses Git to pull only the changes to the project/repository then mod mode will work provided you have not built any of the files that require updating during development, if you do then again you will need to use either the hash or hybrid modes.

How do build-updated (ie. incremental builds) and status work?

While Nift is easiest to learn and understand by using, you 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 you 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?

Nift can use both file modification times and file hashes to track modifications to file dependencies, see the docs page for the incr-mode command for more information than below.

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.

The value stored in a hash file for a tracked file is the hash value of the file from the last time the output file was built. If the hash file does not exist, Nift will flag the file for building.

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 you that any relevant output files require building, and upon 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 documentation page for the function dep.