Folder

Overview

Folder objects represent a folder on the file system, whether it exists or not, based on its path.

To get or create Folder objects, you can:

To check if a given Item object is a Folder, you can use the instanceof operator.

Methods and properties

Getting an instance from an absolute path

Folder Folder(String absolutePath)

Returns a new Folder instance for absolutePath.
On Windows, the path can optionally include a drive identifier.
absolutePath
The absolute path to the folder to get.
sample Get a folder by absolute path
const fonts = Folder('/System/Library/Fonts/');
sample Get a file on a specific Windows drive
const directXLog = File('C:/Windows/DirectX.log');

Creating, deleting, checking existence and comparing

exists Boolean

Whether or not the folder exists on disk.
If there is an item of the same name which isn't a folder, returns false.
Read-only.
sample Check if a file exists
let newFile = here.file('new-file.txt');

cli.tell(newFile.exists); // `false`

newFile.make();
cli.tell(newFile.exists); // now `true`

self make([Boolean forgiving])

Creates the folder based on its path.
Throws if the parent doesn't exist, or if there is already an item at that path.
forgiving
If true:
  • If the parent doesn't exist, make() doesn't throw and creates the parent folder and any missing parent folder.
  • If there is already an item of the same name, only throws if the item is not a folder. If it is a folder, does not modify it.
Defaults to false.
sample Create a file
let newFile = here.file('new-file.txt');
newFile.make();

cli.tell(newFile.exists); // now `true`
sample Create a file and its parents
let packageFolder = here.folder('new-package/');
let packageMetadata = here.file('new-package/package.json');

cli.tell(packageFolder.exists); // `false`
cli.tell(packageMetadata.exists); // `false`

packageMetadata.make(true);

cli.tell(packageFolder.exists); // `true`
cli.tell(packageMetadata.exists); // `true`

Folder copyTo(Folder destination, [Boolean forgiving])

Copies the folder into the destination folder, and returns a Folder object representing the copy.
Throws if there already exists an item of the same name at the destination, or if the destination doesn't exist.
destination
The folder in which to create the copy.
forgiving
If true, if destination doesn't exist, copyTo() doesn't throw and creates destination and any missing parent folder.
Defaults to false.
sample Copy a file and give the copy a new name
const playerSheetTemplate = here.file('templates/player-sheet.template.md');

let newPlayerSheet = playerSheetTemplate.copyTo(here);
newPlayerSheet.name = 'player-sheet.md';

Folder duplicate([String newName])

Creates a copy of the folder in the same folder, and returns a Folder object representing the copy. The name of the copy is derived from the folder's name.
newName
The name to use for the copy instead of an automatically-picked one. duplicate() will throw if the name is taken.
sample Duplicate a file then move the copy somewhere else
const playerSheetTemplate = here.file('templates/player-sheet.template.md');

let newPlayerSheet = playerSheetTemplate.duplicate('player-sheet.md');
newPlayerSheet.moveTo(here);

self delete([Boolean immediately])

Deletes the folder by moving it to the user's trash.
Implemented using the trash package.
immediately
If true, the folder is deleted right away instead of being placed in the trash.
Defaults to false.
sample Clean up after an operation
const keepLog = await cli.ask('Keep log file?', Boolean);
if (!keepLog) here.file('events.log').delete();

Boolean equals(Item other)

Returns true if item is the same (is also a folder, and has the same path).
other
The item to compare with.
sample Ask for two different folders
const sourceFolder = await cli.ask('From?', Folder);
const destinationFolder = await cli.ask('To?', [Folder, function(value) {
		if (value.equals(sourceFolder)) {
			throw 'is the same as the source';
		}
		return value;
	}
]);

cli.tell('Will copy from: ' + sourceFolder.name);
cli.tell('Will copy to: ' + destinationFolder.name);

Name and path

name String

The complete name of the folder, including its extension.
sample Display the name of the first found log file
const someLog = logFolder.children[0];
cli.tell(someLog.name); // "events.log"

bareName String

The name of the folder, without the extension.
sample Get the bareName of a file
const readme = here.file('README.md');
cli.tell(readme.bareName); // "README"

const minifiedMomentFile = here.file('moment.min.js');
cli.tell(minifiedMomentFile.bareName); // "moment.min"
sample Set the bareName of a file
const readme = here.file('README.md');
readme.bareName = 'First steps';
cli.tell(readme.name); // "First steps.md"

extension String

The extension of the folder, such as "txt".

path String

The absolute path to the folder, including its name.
sample Read the path of a folder
cli.tell(home.path); // something like "/Users/cykelero/"

parent Folder

The parent Folder of the folder.
Is null if the item is a file system root.
sample Get the parent of the user folder
const userFolderParent = home.parent;
cli.tell(userFolderParent.path);

self moveTo(Folder destination, [Boolean forgiving])

Moves the folder into the destination folder.
Throws if there already exists an item of the same name at the destination, or if the destination doesn't exist.
destination
The new parent folder.
forgiving
If true, if destination doesn't exist, moveTo() doesn't throw and creates destination and any missing parent folder.
Defaults to false.
sample Move a file
const folderA = here.folder('A/');
const folderB = here.folder('B/');
let file = folderA.file('file.txt');

cli.tell(file.parent.name); // "A"

file.moveTo(folderB);
cli.tell(file.parent.name); // "B"

Metadata

dateCreated Moment

The creation date of the folder. Only supported on macOS.

dateModified Moment

The last modification date of the folder.

user ItemUserPermissions

The ItemUserPermissions object for the folder. Allows reading and modifying the owner of the folder, and the owner's permissions to the folder.
Read-only.
sample Make a file user-executable
const script = here.file('script.js');
script.user.canExecute = true;

group ItemGroupPermissions

The ItemGroupPermissions object for the folder. Allows reading and modifying the owner group of the folder, and the group's permissions to the folder.
Read-only.
sample Make a file group-writeable
const script = here.file('script.js');
script.group.canWrite = true;

other ItemOtherPermissions

The ItemOtherPermissions object for the folder. Allows reading and modifying world permissions to the folder.
Read-only.
sample Make a file world-readable
const script = here.file('script.js');
script.other.canRead = true;

Contents

File file(String relativePath)

Returns a new File instance for relativePath.
Throws if relativePath ends with a slash.
relativePath
The path to the file to get, relative to the path of the folder instance.
sample Get a file by name
const bashProfile = home.file('.bash_profile'); // returns the .bash_profile file from the user's home folder
sample Get a file by path
const hosts = root.file('etc/hosts'); // returns the /etc/hosts file

Folder folder(String relativePath)

Returns a new Folder instance for relativePath.
Throws if relativePath doesn't end with a slash.
relativePath
The path to the folder to get, relative to the path of the folder instance.
sample Get a folder by name
const documents = home.folder('Documents/'); // returns the Documents folder from the user's home folder
sample Get a folder by path
const preferences = home.folder('Library/Preferences/'); // returns the ~/Library/Preferences folder

children Item[]

The list of items contained inside the folder, as File and Folder objects.
Read-only.
sample Remove items without a specific extension from a folder
const buildFolder = here.folder('build/');
buildFolder.children
	.filter(child => child.extension !== 'js')
	.forEach(child => child.delete());

Item[] glob(String pattern, [Object options])

Returns the list of items in the folder that match the glob pattern pattern.
Relies on the glob package.
pattern
The glob pattern.
options
The options to pass to glob. See the glob documentation for a list of supported options.
sample Remove files with a specific extension from a folder
const buildFolder = here.folder('build/');
buildFolder.glob('*.js').forEach(child => child.delete());

size Number

The size of the folder and its children, in bytes.
Read-only.

self empty([Boolean immediately])

Deletes the folder's children by moving them to the user's trash.
Implemented using the trash package.
immediately
If true, the children are deleted right away instead of being placed in the trash.
Defaults to false.
sample Empty a folder
here.folder('build/').empty();

Setting multiple properties at once

self set(Object values)

For each key-value couple in values, sets the key attribute of the Folder to value. This makes it easy to set multiple attributes on the object at once.
values
A map of property names and values.
sample Move and rename a folder in one call
let screenshotFolder = here.folder('screenshots/');
screenshotFolder.set({
	name: 'screenshots-previous',
	parent: here.folder('archive/')
});

return screenshotFolder.name; // returns `'screenshots-previous'`
Folder objects are a type of Item.
See the index for a list of globals representing useful file system locations.