The file command is a magic database first and a program second

A mirror, not the source of truth, and it says so in the description

The GitHub repository description carries the first thing a contributor needs to know: this is a read-only mirror of the file CVS repository, updated every half hour, with an explicit instruction not to open pull requests or comment on commits here. Changes are submitted the usual way, to the bug tracker or to the mailing list, and the description adds that the maintainers are not tracking this Git mirror.

That shapes everything else about the workflow. The authoritative history is CVS, the README links the public repository and the mailing list archives separately, and the file header carries an RCS style keyword with the last revision date and author. GitHub is a convenience surface for reading and searching.

The repository is not archived and the last push was on 2026-10-16, which is consistent with a half hourly sync of a CVS repository that is still active. There are no GitHub releases, so the version lives in the source, and the README points at patchlevel.h for the exact release number rather than a tag.

Everything here is release 5.x of the command, following the USG or System V model of file rather than the V7 or Berkeley variants.

Three sets of tests, run in order

The architecture is easiest to read through the source file list in the README, because each file is one stage of the identification pipeline.

`fsmagic.c` is the first set of tests, based on filesystem information: what the file is called and what the filesystem says about it. `softmagic.c` is the second set, based on the magic database, which is what `apprentice.c` parses. `ascmagic.c` is the third and last set, described in the README as based on hardwired assumptions, which is where text encoding detection lives and where `encoding.c` and `names.h` come in.

Between those sits the compression and container handling. `compress.c` decompresses files to look inside them, `readcdf.c` wraps the Microsoft Compound Document parser in `cdf.[ch]` with `cdf_time.c` for its timestamps, `readelf.[ch]` parses ELF independently of the magic database, and `is_tar.c`, `is_csv.c` for RFC 4180, `is_json.c` for RFC 8259 and `is_simh.c` for SIMH tape images are the hand written recognisers for formats that do not have a magic number worth matching.

There is also `der.[ch]` for Distinguished Encoding Rules, which is certificate and ASN.1 territory. Supporting all of this is why the program depends on a data file rather than only on code.

libmagic is the part third party programs actually use

The 4.x refactoring split the code into a library, with the file command rewritten in terms of it, and the README is explicit about why that matters: libmagic lets third party programs identify file types without having to fork() and exec() file. Mans Rullgard is credited as the prime contributor for 4.0.

The API lives in `src/magic.c`, described in the README as the libmagic api, with `magic.h.in` generating `magic.h`. The build produces `libmagic.pc.in`, a pkg-config file, so linking against it is the conventional path rather than hand written flags.

Calling the command as a subprocess is the pattern this library exists to replace, and it is worth being precise about why that is worse. You parse human readable output, you pay a process spawn per file, and you cannot get structured fields such as the MIME type or the specific match without re-parsing the line. The 5.x changes named in the README include an overhaul in mime and ascii encoding handling, which is exactly the kind of output that a text format makes awkward to consume.

The command itself is `src/file.c`, with `src/file_opts.h` listing the options, `src/print.c` producing results and errors, and `src/buffer.c`, `funcs.c`, `swap.c` and `swap.h` handling byte order and buffers.

Adding a magic entry has editorial rules

Magdir is the directory of magic file pieces, and the README publishes contribution guidelines for anyone submitting a new entry. They are quality rules as much as style rules.

The initial match should be at least 32 bits long and unique. If that is not feasible, add an additional check. Matches of 16 bits or less are not accepted at all, which rules out the shortcut of matching two bytes and hoping. Delay printing the string as much as possible, do not print output early, and avoid using printf with an arbitrary byte as a string, which the README names as a source of crashes and buffer overflows.

Each entry should carry complete information: a one line short summary, an optional long description, the file extension if applicable, a full name and contact method for when the entry misbehaves, and a further reference such as the format documentation.

That last requirement explains something about the data file. The magic database is not auto generated from the formats, so every entry is a human statement about a format, and a format's maintainer is the person who knows when it changed.

The README also explains that the magic file is built from a subdirectory for easier maintenance, and there is a `make-curated-magic.sh` script at the repository root, which is how the pieces in Magdir get combined into the file the command loads.

Verifying what you downloaded, and the security surfaces around it

The README documents a GPG verification procedure for release tarballs, showing the verify step and the keyserver fetch command with placeholder key IDs. The point of documenting it is that a file identification tool is distributed widely and verifies arbitrary untrusted input, which makes it worth installing from a verified source.

That input side is the security surface. `ascmagic.c` guesses encodings of files it does not understand, `compress.c` decompresses untrusted data to look inside, and the CDF, DER and ELF parsers all handle structures whose declared sizes come from the file itself. Two files in the source list address that directly: `landlock.c` for Linux landlock protection and `seccomp.c` for Linux seccomp protection.

Sandboxing file itself with seccomp and landlock reduces what a malformed input can reach if a parser bug is found. That is a partial mitigation, and it is Linux only, since both mechanisms are Linux interfaces.

Getting a verified copy is the other half of that. The README documents the release download path as an FTP location on ftp.astron.com, and then shows how to check the signature before you unpack anything:

gpg --verify file-X.YY.tar.gz.asc file-X.YY.tar.gz

If the signature does not check out, fetch the key from a keyserver and look at it before trusting it:

gpg --keyserver hkp://keys.gnupg.net --recv-keys KKKKKKKK

The key ID is a placeholder in the README's example. The repository also links a Travis CI build status page and an INSTALL document for the build itself, which is autotools based on the configure.ac and Makefile.am in the root.

The project also lists a fuzzing link through the OSS-Fuzz issue tracker and includes a fuzz/ directory in the repository.

Portability claims and a maintainership note

The README claims release 5.x is the standard file command for Linux, the BSDs and other systems, and that it has compiled in numerous environments with PORTING documenting the list and the problems. There is a Makefile.am and configure.ac, so the build is autotools, and there is an acinclude.m4 for the macros it needs.

The most unusual portability entry is AmigaOS. `libmagic` and file cross-compile for AmigaOS 3 on m68k, AmigaOS 4 on PPC and MorphOS on PPC, using container images tagged `sacredbanana/amiga-compiler`, with matching host triplets. Supporting scripts at the root include `amiga-variants.sh` and `package-amiga.sh`.

The README ends with an unusual joke, including an instruction not to telephone the maintainer and to send cash first. It also names a historical footnote: parts of the software were developed at SoftQuad in Toronto, a company acquired by Corel in 2002 that no longer exists.

Contributions are wanted through a mailing list and a bug tracker rather than the repository itself, and the documentation for the two man pages lives in doc/, with a note that the magic man page is installed as magic.4 on USG systems and magic.5 on V7 or Berkeley systems.

Editorial conclusion

Adopt libmagic when your own program needs to identify file types in process, because the alternative is forking and exec'ing the file command and parsing its human readable output, which the 4.x refactoring exists to avoid. Do not send pull requests to this repository: the description states it is a read-only CVS mirror updated every half hour, with changes going to the bug tracker at bugs.astron.com or the [email protected] mailing list. Verify first which magic source your system file command loads, since the command and the magic database version together determine the answers, and a database older than the binary will silently misidentify new formats.

Frequently asked questions

Official sources

1. file/file on GitHub
2. Issues
3. Project website
4. README