Contents

• fileicon — introduction
• Examples
• Installation
  • Installation via Homebrew
  • Installation from the npm registry
  • Manual installation
• Usage
• License
  • Acknowledgements
  • npm dependencies
• Changelog

fileicon — introduction

fileicon

fileicon

Caveat: Custom icons rely on extended attributes of the macOS filesystems, HFS+ and APFS. Therefore, custom icons are lost when copying files or folders to filesystems that don't support these attributes; for instance, custom icons cannot be stored in a Git repository.

When assigning an image file with

fileicon set

Icon\r

The icon with the highest resolution measures 512 x 512 pixels, and the input image is scaled accordingly.
Note that input images that aren't square can result in distorted icons; for best results, provide square images.

Note that if you supply an input path to a symlink, it is invariably its target that is used for the operation; symlinks themselves cannot have icons associated with them.

Examples

# Assign custom icon derived from image file 'img.png' to file 'foo':
fileicon set foo img.png

Remove previously assigned custom icon from folder 'foodir':
fileicon rm foodir
Extract custom icon from file 'foo' to icon file 'foo.icns':
fileicon get foo
Test if folder 'foodir' has custom icon:
fileicon test foodir

Installation

Supported platforms:

• macOS

Installation via Homebrew

With Homebrew installed, run the following:

brew install fileicon

^{Tip of the hat to @danielbayley for creating and submitting the formula.}

Installation from the npm registry

With Node.js installed, install the package as follows:

[sudo] npm install fileicon -g

Note:

• Whether you need

  sudo

  depends on how you installed Node.js and whether you've changed permissions later; if you get an

  EACCES

  error, try again with

  sudo

  .
• The

  -g

  ensures global installation and is needed to put

  fileicon

  in your system's

  $PATH

  .

Manual installation

• Download the CLI as

  fileicon

  .
• Make it executable with

  chmod +x fileicon

  .
• Move it or symlink it to a folder in your

  $PATH

  , such as

  /usr/local/bin

  (requires

  sudo

  ).

Usage

Find concise usage information below; for complete documentation, read the manual online, or, once installed, run

man fileicon

fileicon --man

$ fileicon --help


Manage custom icons for files and folders on macOS.  

SET a custom icon for a file or folder:

    fileicon set       []

REMOVE a custom icon from a file or folder:

    fileicon rm       

GET a file or folder's custom icon:

    fileicon get [-f]  []

    -f ... force replacement of existing output file

TEST if a file or folder has a custom icon:

    fileicon test     

All forms: option -q silences status output.

Standard options: --help, --man, --version, --home

License

Copyright (c) 2015-2019 Michael Klement [email protected] (http://same2u.net), released under the MIT license.

Acknowledgements

This project gratefully depends on the following open-source components, according to the terms of their respective licenses.

npm dependencies below have optional suffixes denoting the type of dependency; the absence of a suffix denotes a required run-time dependency:

(D)

(O)

(P)

npm dependencies

• doctoc (D)
• json (D)
• marked (D)
• marked-man (D)
• replace (D)
• semver (D)
• tap (D)
• urchin (D)

Changelog

Versioning complies with semantic versioning (semver).

• v0.2.4 (2019-12-10):

  • [installation] Thanks to @danielbayley, there is now an official Homebrew formula.

• v0.2.3 (2019-11-01):

  • [enhancement] Installation via Homebrew is now possible on macOS.
  • [doc]

    README.md

    updated with Homebrew installation instructions.
  • [dev] Updated dev-time-only packages to fix security issues.

• v0.2.2 (2018-03-05):

  • [enhancement]

    filecon set 

    is now short for

    filecon set  

    ; that is, you can now more conveniently make an image file use itself as its icon.

• v0.2.1 (2018-01-13):

  • [doc] Read-me improvements re supported image formats.
  • [enhancement] Improved wording of error message on attempting to use a pipe such as via a process subsitution (

    ) in lieu of an actual image file,
    which is not supported.

• v0.2.0 (2017-10-14):

  • [compatibility] macOS 10.13 (High Sierra) is now supported.
  • [enhancement] Switched from using

    sips -i

    for icon creation to a Python-based Cocoa call to

    NSWorkSpace.setIcon(_:forFile:options:)

    , courtesy of https://apple.stackexchange.com/a/161984/28668 As a result, icons in multiple resolutions are now generated, with a top resolution of 512 x 512 pixels (previously: 128 x 128)
  • [doc] More technical background added to

    README.md

    .
  • [usability] subcommands are now case-insensitive, and 'remove' is supported as an alias of 'rm'.

• v0.1.8 (2016-04-21):

  • [dev] Refactored exit-code reporting for the 'get' command (no change in functionality.)
  • [dev]

    TODO.md

    added.

• v0.1.7 (2016-04-21):

  • [fix] Stored-npm-credentials detection code in the Makefile updated for newer npm versions.
  • [fix] Folder write test is now properly skipped for 'get' and 'test' commands - thanks, @zmwangx.
  • [fix] 'get' command now properly reports errors if icon extracton fails
    • thanks, @zmwangx.
  • [dev] Insignificant trailing whitespace removed - thanks, @zmwangx.
    
  • [dev] Added folder used by tests that was missing from the repo.

• v0.1.6 (2015-09-16):

  • [doc] Man-page improvements.
  • [dev] Makefile improvements.

• v0.1.5 (2015-09-15):

  • [doc] Man-page improvements.
  • [dev] Makefile improvements.

• v0.1.4 (2015-09-14):

  • [fix] Spurious error message no longer prints when invoking

    fileicon --man

    on a system where the man page isn't installed.
  • [doc] Read-me improvements.

• v0.1.3 (2015-09-02):

  • [dev, doc] minor tweaks

• v0.1.2 (2015-08-04):

  • [doc] Read-me and manual enhancements.

• v0.1.1 (2015-08-03):

  • [doc] Read-me and manual enhancements.
  • [dev] Permission-related tests added.

• v0.1.0 (2015-08-03):

  • Initial release.