immutable-file v1.1.0
immutable-file
A tool to lock down commits against project files you don't want touched.
Purpose
This tool allows files to be marked as "immutable" by storing their paths in a config file, these will then be checked against any staged git changes.
This is useful to add a precommit check for collaborative projects (or even just you!), where you want to guarantee things like database migrations don't get edited.
Getting Started
Installation
You can install immutable-file directly into your project with:
npm i immutable-file --save-dev
or yarn add immutable-file --dev
If you also install globally, there is other useful CLI functionality
npm i -f immutable-file
or yarn global add immutable-file
If you have the global install above, you can now run immutable-file --init
in
your project to automatically create a immutable-file.json
in your root.
Alternatively, you can just make an immutable-file.json
in your project (And
configure as explained in the next section)
Configuration
Immutable-file config is JSON in the following shape:
{
"error": "These migrations should not be edited!",
"lock": [
"./relative/path/to/file/you/want/locked"
]
}
This config file should be kept in your project version control to allow the auditing between collaborators.
The error
key is a string that will get cited as the reason for failing an
immutable-file audit (They've tried to commit with a file in the lock array
staged).
The lock
key is just an array of relative paths to the files you want to block
commits against.
Precommit git hook
This library best used as a precommit hook, so that the audit is run
automatically. To do this, install Husky to
your project and add the following to your package.json
"scripts": {
"precommit": "immutable-file"
}
Marking a file as immutable
If you have immutable-file installed globally, you can just run immutable-file
-f <path>
to have it automatically inserted into the immutable-file.json
file, or you can do this manually of course.
If you'd like to add multiple files, you can add them by calling immutable-file
--glob <glob>
flag. This will calculate the relevant paths to add at that
point in time and add them seperately to the lock list.