balena-image-fs

Balena.io image filesystem manipulation utilities.

Role

The intention of this module is to provide low level utilities to Balena.io operating system data partitions.

THIS MODULE IS LOW LEVEL AND IS NOT MEANT TO BE USED BY END USERS DIRECTLY.

Installation

Install balena-image-fs by running:

$ npm install --save balena-image-fs

Documentation

imagefs~interact()

Kind: inner method of imagefs
Summary: Run a function with a node fs like interface for a partition
Example

const contents = await interact('/foo/bar.img', 5, async (fs) => {
    return await promisify(fs.readFile)('/bar/qux');
});
console.log(contents);

Support

If you're having any problem, please raise an issue on GitHub and the Balena.io team will be happy to help.

Tests

Run the test suite by doing:

$ npm test

Contribute

• Issue Tracker: github.com/balena-io-modules/balena-image-fs/issues
• Source Code: github.com/balena-io-modules/balena-image-fs

License

The project is licensed under the Apache 2.0 license.

Change Log

All notable changes to this project will be documented in this file automatically by Versionist. DO NOT EDIT THIS FILE MANUALLY! This project adheres to Semantic Versioning.

7.5.3 - 2025-04-02

• Update dependency mocha to v11 [balena-renovate[bot]]

7.5.2 - 2025-04-02

• Update dependency jsdoc-to-markdown to v9 [balena-renovate[bot]]

7.5.1 - 2025-03-26

• Update @balena/lint to v9 [Thodoris Greasidis]
• Remove the no longer needed gpt detection helper [Thodoris Greasidis]
• Update TypeScript to 5.8.2 [Thodoris Greasidis]
• Drop the package-lock.json [Thodoris Greasidis]

7.5.0 - 2025-03-26

• Add function to find a partition by name/label [Ken Bannister]

7.4.1 - 2025-02-21

• bump ext2fs to 4.2.4 [Ryan Cooke]

7.4.0 - 2025-01-27

• Add getLabel() to retrieve filesystem label [Ken Bannister]

7.3.0 - 2025-01-06

• Drop Bluebird from devDependencies [Thodoris Greasidis]
• flowzone: Remove empty with clause [Thodoris Greasidis]
• Add the promises namespace as part of the exposed fs [Thodoris Greasidis]

7.2.2 - 2024-01-02

• Update dependency @types/node to v20 [Self-hosted Renovate Bot]

7.2.1 - 2023-12-19

• Remove repo config from flowzone.yml [Kyle Harding]

7.2.0 - 2023-01-20

• Add support for Node 18 [Akis Kesoglou]

7.1.2 - 2023-01-05

• Update dependencies [ab77]

7.1.1 - 2022-12-20

• Update dependency jsdoc-to-markdown to 8.0.0 [Renovate Bot]

7.1.0 - 2022-12-13

• update dependencies [Zane Hitchcox]

7.0.6 - 2020-12-02

7.0.5 - 2020-11-27

• Add versionbot changelog [Alexis Svinartchouk]

v7.0.4

(2020-11-05)

• Update ext2fs to ^3.0.3 [Alexis Svinartchouk]

v7.0.3

(2020-10-27)

• Try fat before ext in interact [Alexis Svinartchouk]

v7.0.2

(2020-09-03)

• Fix wrong error being thrown for fat partition errors [Alexis Svinartchouk]

v7.0.1

(2020-08-04)

• Add .versionbot/CHANGELOG.yml for nested changelogs [Pagan Gazzard]

v7.0.0

(2020-07-30)

• Replace wary with mocha [Alexis Svinartchouk]
• Rename resin -> balena [Alexis Svinartchouk]
• lint on pre-commit [Alexis Svinartchouk]
• Convert to typescript [Alexis Svinartchouk]
• Simplify, only leave the interact function [Alexis Svinartchouk]
• Stop using lodash [Alexis Svinartchouk]

v6.0.0

(2020-07-24)

• Update file-disk to ^7 [Alexis Svinartchouk]

5.0.9 - 2020-03-02

• Update dev dependencies [Pagan Gazzard]

5.0.8 - 2019-05-06

• Add bump node-ext2fs ^1.0.28 and and support/CI testing for Node 12/10 [Gergely Imreh]

5.0.7 - 2019-04-04

• Update file-disk to ^6.0.0 [Alexis Svinartchouk]
• Update jsdoc-to-markdown [Alexis Svinartchouk]

5.0.6 - 2019-01-14

• Update partitioninfo to ^5.2.0 [Alexis Svinartchouk]

5.0.5 - 2018-11-29

• Update file-disk to 5.0.0 [Alexis Svinartchouk]

v5.0.4 - 2018-05-01

• Don't require chalk in utils.coffee #41 [Alexis Svinartchouk]

v5.0.3 - 2018-04-30

• Only require fatfs when it's needed. #39 [Pagan Gazzard]

v5.0.2 - 2018-04-25

• Change the way we try to identify filesystems #38 [Theodor Gherzan]

v5.0.1 - 2018-04-25

• Update ext2fs to 1.0.4 #37 [Theodor Gherzan]

v5.0.0 - 2018-03-30

• Update file-disk, partitioninfo and node-ext2fs #36 [Alexis Svinartchouk]
• Don't version built files #36 [Alexis Svinartchouk]
• Update lodash to v4 #36 [Alexis Svinartchouk]

v4.1.2 - 2018-01-25

• Throw an error when partition == 0, fix docs. #34 [Alexis Svinartchouk]

v4.1.1 - 2017-12-11

• Refactor read stream logic to improve clarity & error handling #32 [Tim Perry]
• Update Bluebird to v3 #32 [Tim Perry]

v4.1.0 - 2017-11-21

• Upgrade partitioninfo so we can read GPT partition tables too #31 [Tim Perry]
• Upgrade to new ext2fs with prebuilt packages available #31 [Tim Perry]

v4.0.2 - 2017-10-18

Fixed

• Make errors on read streams safe, by delaying read until someone is attached

v4.0.1 - 2017-06-23

Fixed

• Fixed creating files in ext partitions with paths that do not start with '/'.

v4.0.0 - 2017-06-19

Changed

• All methods that take a partition as a parameter now expect the partition number instead of {primary: X, logical: Y}.

v3.0.0 - 2017-06-16

Added

• Support for ext2, ext3 and ext4 filesystems.
• imagefs.interact(disk, partition) returns a disposer of a node fs like interface. Sync methods are not supported.

Changed

• imagefs.listDirectory() lists all files, including those that start with a dot.
• imagefs.write, imagefs.copy and imagefs.replace now return a Promise instead of a Promise<WriteStream>.
• imagefs.read now returns a disposer<ReadStream> instead of a Promise<ReadStream>.
• All methods now accept filedisk.Disk instances as well as image paths.

Fixed

• Logical partitions are now correctly handled.

v2.3.0 - 2016-10-05

Added

• Implement imagefs.listDirectory().

v2.2.0 - 2016-10-03

Added

• Implement imagefs.readFile().
• Implement imagefs.writeFile().

v2.1.2 - 2015-12-04

Changed

• Reduce package size by omitting tests in NPM.

v2.1.1 - 2015-10-13

Changed

• Close drive file descriptor after any operation.

v2.1.0 - 2015-07-28

Added

• Implement imagefs.replace() function.

v2.0.1 - 2015-07-27

Changed

• Fix documentation issues.

Removed

• FAT file touch workaround before write.

v2.0.0 - 2015-07-23

Changed

• Use object path definitions instead of image:(partition):/path device paths.

Removed

• Local file read/write support.