phatsort-0.6.0.0: README.md
# PhatSort
[](https://www.repostatus.org/#active)
[](https://github.com/ExtremaIS/phatsort-haskell/actions)
[](https://hackage.haskell.org/package/phatsort)
[](https://stackage.org/package/phatsort)
[](https://stackage.org/nightly/package/phatsort)
* [Overview](#overview)
* [CLI](#cli)
* [Requirements](#requirements)
* [Installation](#installation)
* [`.deb` Package Installation](#deb-package-installation)
* [`.rpm` Package Installation](#rpm-package-installation)
* [Installation From Hackage](#installation-from-hackage)
* [Installation From Stackage](#installation-from-stackage)
* [Usage](#usage)
* [Related Software](#related-software)
* [Project](#project)
* [Links](#links)
* [Tags](#tags)
* [Contribution](#contribution)
* [License](#license)
## Overview
The PhatSort project provides two command-line utilities for sorting files
and directories on FAT filesystems. The `phatsort` utility sorts files and
directories that are already on the filesystem. The `seqcp` utility copies
files and directories to the filesystem in sorted order.
There are many MP3 players that allow you to mount the device as external
storage and manage the media yourself. The storage generally uses a FAT
filesystem. When copying multiple files onto the storage, using the command
line (`cp`/`mv`) or a GUI, they are generally stored in an arbitrary order.
This is not a problem if the firmware of the MP3 player sorts by filename, but
many MP3 players use the order in the FAT filesystem without sorting, which
results in podcasts and album tracks being played out of order.
There are some utilities that sort the FAT tables of an unmounted filesystem.
(See [Related Software](#related-software) for information and links.)
Unfortunately, there are many devices for which this does not work. PhatSort
takes a different approach to solving the problem. It works by creating new
directories and moving ("renaming") the files in the desired order, while the
filesystem is mounted. This method works on all devices that have been tried
so far.
PhatSort also (optionally) forces the filesystem buffers to be written to the
storage media after each change. This helps avoid write failures when using
devices that have problems with writing large amounts of data. Note that the
`seqcp` utility helps with this issue even on non-FAT filesystems.
## CLI
### Requirements
PhatSort has only been tested on Linux. It *might* work on other operating
systems. Scripts that are output use POSIX shell commands and therefore
require a POSIX shell to execute.
### Installation
#### `.deb` Package Installation
Check the [Releases][] page for `.deb` packages.
#### `.rpm` Package Installation
[Releases]: <https://github.com/ExtremaIS/phatsort-haskell/releases>
Check the [Releases][] page for `.rpm` packages.
#### Installation From Hackage
Install PhatSort from [Hackage][] using [Cabal][] as follows:
```
$ cabal v2-install phatsort
```
[Hackage]: <https://hackage.haskell.org/package/phatsort>
[Cabal]: <https://www.haskell.org/cabal/>
#### Installation From Stackage
Install PhatSort from [Stackage][] using [Stack][] as follows:
```
$ stack install phatsort
```
[Stackage]: <https://www.stackage.org/package/phatsort>
[Stack]: <https://haskellstack.org/>
### Usage
See the [`phatsort`][] and [`seqcp`][] man pages for usage information.
[`phatsort`]: <doc/phatsort.1.md>
[`seqcp`]: <doc/seqcp.1.md>
## Related Software
[`FATSort`][] is a command-line utility that sorts unmounted FAT filesystems
by direct manipulation of the FAT tables. Unfortunately, there are many
devices for which this does not work.
[`YAFS`][] is a command-line utility that sorts unmounted FAT filesystems by
direct manipulation of the FAT tables. [`Visual YAFS`][] provides a GUI. I
have not tried either of these.
[`DriveSort`][] is Windows GUI software that sorts unmounted FAT filesystems
by direct manipulation of the FAT tables. I have not tried it.
[`FATSort`]: <https://fatsort.sourceforge.io/>
[`YAFS`]: <http://www.luisrios.eti.br/public/en_us/projects/yafs/>
[`Visual YAFS`]: <http://www.luisrios.eti.br/public/en_us/projects/visual_yafs/>
[`DriveSort`]: <http://www.anerty.net/software/file/DriveSort/>
## Project
### Links
* Hackage: <https://hackage.haskell.org/package/phatsort>
* Stackage: <https://www.stackage.org/package/phatsort>
* Flora: <https://flora.pm/packages/@hackage/phatsort>
* GitHub: <https://github.com/ExtremaIS/phatsort-haskell>
* GitHub Actions CI: <https://github.com/ExtremaIS/phatsort-haskell/actions>
### Branches
The `main` branch is reserved for releases. It may be considered stable, and
`HEAD` is always the latest release.
The `develop` branch is the primary development branch. It contains changes
that have not yet been released, and it is not necessarily stable.
[Hackage revisions][] are made for metadata changes, such as relaxation of
constraints when new versions of dependencies are released. The
`phatsort.cabal` metadata in the `main` branch may therefore not match that of
Hackage. The `phatsort.cabal` metadata in the `develop` branch may match,
*unless* work is being done on a new release that contains other changes.
[Hackage revisions]: <https://github.com/haskell-infra/hackage-trustees/blob/master/revisions-information.md#hackage-metadata-revisions--what-they-are-how-they-work>
### Tags
All releases are tagged in the `main` branch. Release tags are signed using
the [`security@extrema.is` GPG key][].
[`security@extrema.is` GPG key]: <https://keyserver.ubuntu.com/pks/lookup?search=0x1D484E4B4705FADF&fingerprint=on&op=index>
### Contribution
Issues and feature requests are tracked on GitHub:
<https://github.com/ExtremaIS/phatsort-haskell/issues>
Issues may also be submitted via email to <bugs@extrema.is>.
### License
This project is released under the [MIT License][] as specified in the
[`LICENSE`][] file.
[MIT License]: <https://opensource.org/licenses/MIT>
[`LICENSE`]: <LICENSE>