Swiss Army knife for Unix permissions.
Unix file permissions
can take many shapes: symbolic
(ug+rw
), octal (660
) or a
list of characters (drw-rw----
). This library enables
using any of these (instead of being limited to a single
one) with any Node.js or CLI command.
This library can also perform operations on Unix permissions such as:
|
, &
,
^
, ~
) can be tedious and error-prone otherwise.u+r,u+w
can be
shortened to u+rw
.umask
of 117
means new files will be
created with 661
permissions.Permissions are manipulated as strings, not as file paths. This means you must
use other utilities (such as chmod
or
stat
) to get and set file permissions
using those strings.
In JavaScript:
// Retrieve a file's permission as an object like
// `{ user: { write: false, read: true, ... }, ... }` instead of a number
convert.object(fs.statSync('/etc/passwd').mode)
// Set a file's permission using `symbolic` notation instead of a number
fs.chmod('/etc/passwd', convert.number('a=r'))
// Set a file's permission using `symbolic` notation instead of a number
fs.writeFile('/my/file', content, { mode: convert.number('a=r') })
// Disallow executing new files using `umask`
process.umask(convert.number(invert('a-x')))
// If your library takes Unix permissions as input, using
// `unix-permissions` under the hood lets your users choose their
// favorite Unix permissions type.
myLibrary.method({ mode: 'a-wx' })
myLibrary.method({ mode: '444' })
On the command line:
$ stat -c "%a" /etc/passwd
644
$ unix-permissions convert.symbolic "$(stat -c "%a" /etc/passwd)"
u=rw,go=r
You can try this library:
examples
files in a terminal.npm install unix-permissions
const { convert } = require('unix-permissions')
// `permission` will be set to `rw-rw----`
const permission = convert.stat('660')
Several methods other than convert
are available but they mostly follow the
same pattern. Permission strings are passed as input and returned as output.
$ unix-permissions convert.stat 660
rw-rw----
The same methods as in JavaScript are available. Exit code will be 1
if an
error occurred, e.g. if the permission syntax is invalid.
You can use any of the following permission types as input. You can also
convert()
between them:
octal
strings like "422"
number
like 274
stat
like rw-rw-r--
symbolic
like a+rw
object
like
{ user: { read: true, write: false, execute: false }, group: { write: false }, others: { write: false } }
Special permissions (setuid, setgid, sticky) can be used.
Please see the types full documentation.
Converts permission
to another type.
Full documentation.
Returns the permission
's type or invalid
.
Full documentation.
Normalizes a permission
to its canonical shape. Throw if permission
is
invalid.
Full documentation.
Removes all negative permissions.
Full documentation.
Tests whether permission
includes permissions
.
Full documentation.
Tests whether permission
equals exactly permissions
.
Full documentation.
Sets permissions
on permission
. This is useful to avoid error-prone bitwise
operations (|
, &
, ^
, ~
).
Full documentation.
Inverts permission
including special permissions. This can be used in
combination with set()
to unset permissions
instead of setting them.
Full documentation.
Inverts permission
and removes special permissions.
Full documentation.
Retrieves the lowest permissions among all arguments.
Full documentation.
Retrieves the highest permissions among all arguments.
Full documentation.
If you found a bug or would like a new feature, don't hesitate to submit an issue on GitHub.
For other questions, feel free to chat with us on Gitter.
Everyone is welcome regardless of personal background. We enforce a Code of conduct in order to promote a positive and inclusive environment.
This project was made with ❤️. The simplest way to give back is by starring and sharing it online.
If the documentation is unclear or has a typo, please click on the page's Edit
button (pencil icon) and suggest a correction.
If you would like to help us fix a bug or add a new feature, please check our guidelines. Pull requests are welcome!
ehmicky 💻 🎨 🤔 📖 |