fileicon

by mklement0

mklement0 / fileicon

macOS CLI for managing custom icons for files and folders

150 Stars 9 Forks Last release: Not found 33 Commits 17 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

npm version license

Contents

fileicon — introduction

fileicon
is a macOS CLI for managing custom icons for files and folders, as a programmatic alternative to interactively using Finder.

fileicon
allows assigning a custom icon to any file or folder, using any image file whose format is recognized by the system.

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
, a set of icons in several resolutions is created and stored in the resource fork of the target file itself / of a hidden
Icon\r
file inside the target folder.

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.

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
if installed manually).
$ 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)
denotes a development-time-only dependency,
(O)
an optional dependency, and
(P)
a peer dependency.

npm dependencies

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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.