CLI tool
onevcat/FengNiao avatar
onevcat/FengNiao

FengNiao deletes files it cannot restore, and two of its badges point at other projects

A command line tool for cleaning unused resources in Xcode.

3,576 stars246 forksSwiftMIT

At a glance

What is it?
FengNiao is a Swift command line tool that finds image resources no source file mentions and deletes them. Its install instructions end in a sudo copy into /usr/local/bin, its build phase recipe runs with the force flag so nothing is confirmed, and its own how-it-works list disagrees with its help text about whether plist files are scanned.
Who is it for?
FengNiao is worth running once, on a clean branch, in a project whose assets came from a designer rather than from your own code, because the mechanism is deliberately simple: it extracts resource names, searches the source for those names as strings, and treats whatever is left as unused. That simplicity is the risk.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Activity is slowing. The repository last received commits 6 months ago.
What is it written in?
Mainly Swift, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • onevcat/FengNiao3,576 ★ · +2
Star history
Repository2026-09-242026-11-15
onevcat/FengNiao3.6k3.6k

2 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Two of the badges belong to other projects

The header is seven links and five of them are the same badge repeated. What is left over from copy and paste is more interesting. The licence badge at the top does not point at this repository's licence file, it points at the licence file of a different project by the same author, an image library. And the coverage badge points at a third repository, one whose name has nothing to do with this tool at all. So the two badges a reader would use to check what licence applies and how well tested this is both resolve to something else. The continuous integration badge points at a service whose configuration file is still committed at the repository root, and the root also carries a coverage configuration file, so the badges are stale in a way the tree contradicts.

The deletion cannot be undone

The usage section is short. You move to your project folder, run the tool, and it scans the current directory and everything below it for unused images, then asks whether you want them deleted. The warning that follows is the important part of the page: it tells you to make sure you have a backup or a version control system first, and calls the operation un-restorable. Nothing in the tool takes a copy, keeps a trash directory or writes a manifest, so the safety of a run depends entirely on what your version control does when it sees a deletion. For a project where image assets arrive from a design tool and are referenced from storyboards and asset catalogues, that is a reasonable trade. For a project with assets referenced from plist files, it needs reading rather than trusting.

The build phase recipe deletes without asking

There is a documented way to run this on every build, and it is worth reading twice. You add a Run Script phase, drag it above the Copy Bundle Resources phase, and fill it in with a single line:

bash
fengniao --exclude Carthage --force

The force option is the one that changes the character of the tool: it deletes what it found without asking. The README recommends excluding vendor folders such as Pods and Carthage, and then says that since you do not have a chance to confirm the result you also need the force option. So the recommended integration is unattended deletion, run on every build, of files the tool believes are unused. The same page that recommends it also says the deletion is un-restorable, which leaves version control as the only thing standing between a misdetection and a broken asset catalogue.

The two lists of scanned files disagree

The tool has two defaults that matter and they are stated twice, in different places, with different contents. The help text says the resource extensions searched are imageset, jpg, png, gif and pdf, and the file types searched for usage are Objective-C, Objective-C++, Swift, xib and storyboard. The how it works section lists the same five resource extensions, and then lists six file types for the usage search, adding plist. So a resource referenced only from a plist file is scanned according to one part of the documentation and not according to the other. Since the third step is a subtraction, whatever is not found in the searched files is treated as unused, which makes the difference between those two lists a difference between a safe run and a deleted asset.

Detection is a search for strings

The three step summary is the whole algorithm. Extract resource file names from the resource extensions, in the folders that hold imagesets, launch images, app icon sets and the bundle folder. Then use a regular expression to search all string names in the source files. Then exclude the names that were found from the resource list, and what remains is unused. Nothing parses an asset catalogue, nothing follows a symbol reference, and nothing knows about the project's build settings. That is a deliberate trade for a tool that has to work without opening your project, and it explains both the tool's speed and its failure mode: a resource referenced in a way the expression does not match is, as far as the tool is concerned, not referenced at all. The folder list in that first step also ends with a curly quotation mark instead of a plain one, which is a small sign that the list is edited by hand.

The help output stops in the middle of a word

The options are listed in the readme as pasted help output, and six of them are visible. There is a project root path defaulting to the current folder, a force flag for deleting without asking, a flag to exclude paths, one to choose which resource extensions to search, one to choose which file types to search for usage, and one to skip cleaning the references in the project file. The last of those is cut off mid-word, in the middle of its own explanation. The listing also writes the long form of each option with a colon after it, which is not how an option is normally displayed and makes the block look hand-edited rather than captured. Neither problem breaks the tool, but they are the reason the readme's own option list cannot be used as a reference.

Installing ends in a sudo copy and a rename

There are two install routes. The first is a package manager for Swift command line tools, which needs Xcode installed and then two commands, one to install the manager and one to install this tool by its owner and name. The second is building from source: clone the repository, change into the directory, build a release configuration, and then copy the resulting executable into a directory on your path. The copy step in the readme uses a privileged copy into the local binary directory, and it renames the executable from the capitalised project name to a lower case one on the way. Nothing checks that the destination exists, and the README's own summary of the requirement says the tool should be compiled, tested and installed into that directory, which is a stronger instruction than most people follow on a shared machine.

A GUI app exists, and the last section sells a course

Two closing sections are worth knowing about. The first says a graphical version of the tool is available in the App directory of the repository, that no pre-built binary is provided, and that you should build it yourself, with thanks given to the contributor who wrote it. The second is not documentation. It describes a live coding series in Chinese covering how the tool was built, including the Swift package manager, protocol oriented programming, test driven development and writing tests, and it says the series is paid. The naming note sits between them, crediting a Chinese word for hummingbird and calling it the smallest bird in the world. So the readme ends with a course advertisement rather than with a project status, and the tags carry no version prefix at all.

Editorial conclusion

FengNiao is worth running once, on a clean branch, in a project whose assets came from a designer rather than from your own code, because the mechanism is deliberately simple: it extracts resource names, searches the source for those names as strings, and treats whatever is left as unused. That simplicity is the risk. Anything a resource is referenced by in a way the search does not understand will be reported unused, so read the list before you delete anything. And if you wire it into a build phase, use the exclude flag for your dependency folders and keep version control on, because the documented recipe adds the force flag and the README is explicit that the deletion cannot be undone.

Frequently asked questions

What does FengNiao do to an Xcode project?

It deletes unused image resource files. It scans the current folder and its subfolders, works out which resources no source file refers to, and asks whether to delete them. The README warns that the operation cannot be undone and recommends a backup or version control first.

How do I install FengNiao?

Through a Swift command line package manager, after installing Xcode, or from source. Building from source means cloning the repository, changing into it, building a release configuration, and copying the executable to a directory on your PATH. The readme's example copies it with sudo into the local binary directory and renames it to a lower case name.

What arguments does FengNiao take?

A project root path defaulting to the current folder, a force flag to delete without asking, a flag to exclude paths, one to choose which resource extensions to search defaulting to imageset, jpg, png, gif and pdf, one to choose which file types to search for resource usage defaulting to m, mm, swift, xib and storyboard, and a flag to skip cleaning the project file references.

Is it safe to run FengNiao from an Xcode build phase?

The documented recipe is a Run Script phase above the Copy Bundle Resources phase running the tool with the exclude option for vendor folders and the force option, which deletes without asking. The README notes you have no chance to confirm the result in that setup, and elsewhere calls the deletion un-restorable, so version control is effectively a prerequisite.

Does FengNiao have a graphical version?

There is a GUI app in the App directory of the repository, contributed by another person. The README says no pre-built binary is provided for it and that you should build it yourself.

Official sources

  1. Issues
  2. License: MIT
  3. onevcat/FengNiao on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/onevcat-fengniao.svg)](https://hysenlabs.com/projects/onevcat-fengniao)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/onevcat-fengniao.svg)](https://hysenlabs.com/projects/onevcat-fengniao)

Was this useful?