Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,24 @@
# Changelog

## 0.13.1 - 2026-11-14

### Changed

- Stop printing the m, n and f flags in the flags property, which carried no information
- Show an error's number only when the text comes from the operating system

### Fixed

- Find files given with forward slashes in read, extract, remove and rename
- Stop add from leaving files out when one run fills the archive's file table
- Reject a create sector size below 1024 or not a power of two, which StormLib cannot read back
- Accept locale names in any case, so dede is deDE rather than the locale ID 0xDEDE
- Ignore an empty listfile with a warning instead of failing
- List and extract an archive with no entries as empty instead of failing
- Leave no empty output directory behind when extract writes nothing or is interrupted
- Describe Windows system errors with the Windows message rather than an unrelated one
- Describe verify --print as writing raw bytes, not hex, in the help, docs and completions

## 0.13.0 - 2026-10-16

### Added
Expand Down
2 changes: 1 addition & 1 deletion CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
cmake_minimum_required(VERSION 3.25)

project(mpqcli VERSION 0.13.0)
project(mpqcli VERSION 0.13.1)

# An option() name is global to the CMake cache, including a consumer's, so these
# carry the project prefix; a bare BUILD_STATIC claims a name anyone might want.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

![Release Build](https://img.shields.io/github/actions/workflow/status/thegraydot/mpqcli/tag.yml?style=flat&label=release&logo=github) ![Main Build](https://img.shields.io/github/actions/workflow/status/thegraydot/mpqcli/main.yml?style=flat&label=main&logo=github)

![Release Version](https://img.shields.io/github/v/release/thegraydot/mpqcli?style=flat&logo=github) ![Release downloads](https://img.shields.io/github/downloads/thegraydot/mpqcli/total?style=flat&label=downloads&logo=github) ![Package downloads](https://img.shields.io/badge/package_downloads-1.2k-green?style=flat&logo=github)
![Release Version](https://img.shields.io/github/v/release/thegraydot/mpqcli?style=flat&logo=github) ![Release downloads](https://img.shields.io/github/downloads/thegraydot/mpqcli/total?style=flat&label=downloads&logo=github) ![Package downloads](https://img.shields.io/badge/package_downloads-1.3k-green?style=flat&logo=github)

![C++ Version](https://img.shields.io/badge/Version-17-blue?style=flat&logo=cplusplus)

Expand Down
2 changes: 1 addition & 1 deletion docs/advanced.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ $ mpqcli list wow-patch.mpq | grep -i \.exe | mpqcli extract wow-patch.mpq -
[*] Extracted: WowError.exe
```

Note that directories are specified with backslashes. The names reach `mpqcli extract` on stdin unchanged, so only the backslash in the `grep` pattern needs escaping. The following example extracts all `dat` files in the `arr` directory from the `StarDat.mpq` archive, keeping the folder.
Note that `list` prints directories with backslashes, as the archive stores them. The names reach `mpqcli extract` on stdin unchanged, so only the backslash in the `grep` pattern needs escaping. The following example extracts all `dat` files in the `arr` directory from the `StarDat.mpq` archive, keeping the folder.

```bash
$ mpqcli list -l scbw.txt StarDat.mpq | grep -i 'arr\\.*dat$' | sort | mpqcli extract StarDat.mpq -
Expand Down
19 changes: 19 additions & 0 deletions docs/changelog.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,24 @@
# Changelog

## 0.13.1 - 2026-11-14

### Changed

- Stop printing the m, n and f flags in the flags property, which carried no information
- Show an error's number only when the text comes from the operating system

### Fixed

- Find files given with forward slashes in read, extract, remove and rename
- Stop add from leaving files out when one run fills the archive's file table
- Reject a create sector size below 1024 or not a power of two, which StormLib cannot read back
- Accept locale names in any case, so dede is deDE rather than the locale ID 0xDEDE
- Ignore an empty listfile with a warning instead of failing
- List and extract an archive with no entries as empty instead of failing
- Leave no empty output directory behind when extract writes nothing or is interrupted
- Describe Windows system errors with the Windows message rather than an unrelated one
- Describe verify --print as writing raw bytes, not hex, in the help, docs and completions

## 0.13.0 - 2026-10-16

### Added
Expand Down
2 changes: 1 addition & 1 deletion docs/commands/extract.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ The listfile only applies when extracting every file, so it cannot be combined w

## Extract specific files

Name one or more files after the archive to extract only those. A file nested in a directory needs its full path in the archive, and is extracted with its folders; add `--flat` to drop them. Similar to the examples above, you can use the `-o` argument to specify the output directory.
Name one or more files after the archive to extract only those. A file nested in a directory needs its full path in the archive, with its directories separated by `\` or `/`, and is extracted with its folders; add `--flat` to drop them. Similar to the examples above, you can use the `-o` argument to specify the output directory.

```bash
$ mpqcli extract "World of Warcraft_1.12.1.5875/Data/base.MPQ" \
Expand Down
8 changes: 8 additions & 0 deletions docs/commands/read.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,14 @@ $ mpqcli read wow-patch.mpq "WoW.exe" | xxd
00000030: 4504 8080 0280 9002 8098 0281 d801 0585 E...............
```

## Read a file in a directory

Give the file's full path in the archive. Directories can be separated with `\`, as the archive stores them, or with `/`.

```bash
$ mpqcli read Patch_rt.mpq "rez/stat_txt.tbl"
```

## Read one specific file with locale

Use the `-e` or `--locale` argument to specify the locale of the file to read. If there is no file with the requested name and locale, the default locale will be used instead.
Expand Down
3 changes: 3 additions & 0 deletions docs/commands/remove.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ Remove one or more files from an existing MPQ archive.
The archive is always the first positional argument, followed by one or more archive paths
to remove. All removals happen in a single open/close cycle.

Directories in an archive path can be separated with `\`, as the archive stores them, or with
`/`. Messages show the path as the archive stores it.

## Remove a single file

```bash
Expand Down
3 changes: 3 additions & 0 deletions docs/commands/rename.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ The archive is the first positional argument, followed by the current and new ar
This operation does not cause MPQ fragmentation, and thus it is not necessary to
[`compact`](compact.md) the archive.

Directories in either path can be separated with `\` or `/`. The new path is stored with `\`,
and messages show both paths as the archive stores them.

```bash
$ mpqcli rename wow-patch.mpq old-name.txt new-name.txt
[~] Renaming file: old-name.txt -> new-name.txt
Expand Down
13 changes: 7 additions & 6 deletions src/mpq/extract.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -100,15 +100,16 @@ int ExtractFiles(HANDLE archive, const fs::path &output, const std::vector<std::
int ExtractFile(HANDLE archive, const fs::path &output, const std::string &file_name, bool flat,
LCID preferred_locale, std::ostream &err) {
SFileSetLocale(preferred_locale);
if (!FileExistsInArchiveForLocale(archive, file_name.c_str(), preferred_locale) &&
!FileExistsInArchiveForLocale(archive, file_name.c_str(), default_locale)) {
const std::string stored_name = StoredFileName(archive, file_name, preferred_locale);
if (!FileExistsInArchiveForLocale(archive, stored_name, preferred_locale) &&
!FileExistsInArchiveForLocale(archive, stored_name, default_locale)) {
err << "[!] Failed: File doesn't exist"
<< PrettyPrintLocale(preferred_locale, " for locale ", true) << ": " << file_name
<< PrettyPrintLocale(preferred_locale, " for locale ", true) << ": " << stored_name
<< std::endl;
return 1;
}

const std::string file_name_string = ExtractedName(file_name, flat);
const std::string file_name_string = ExtractedName(stored_name, flat);

std::error_code ec;
fs::path output_path_base = fs::absolute(output, ec).lexically_normal();
Expand Down Expand Up @@ -158,11 +159,11 @@ int ExtractFile(HANDLE archive, const fs::path &output, const std::string &file_

std::string output_file_name{output_file_path_name.string()};

if (SFileExtractFile(archive, file_name.c_str(), output_file_name.c_str(), 0)) {
if (SFileExtractFile(archive, stored_name.c_str(), output_file_name.c_str(), 0)) {
err << "[*] Extracted: " << file_name_string << std::endl;
} else {
const auto error = SErrGetLastError();
err << "[!] Failed: " << StormErrorString(error) << ": " << file_name << std::endl;
err << "[!] Failed: " << StormErrorString(error) << ": " << stored_name << std::endl;
return 1;
}

Expand Down
16 changes: 16 additions & 0 deletions src/mpq/query.cpp
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
#include "mpq/query.h"

#include <algorithm>
#include <cstdint>
#include <cstring>
#include <filesystem>
Expand Down Expand Up @@ -32,6 +33,21 @@ bool FileExistsInArchiveForLocale(const HANDLE archive, const std::string &file_
return file_exists;
}

std::string StoredFileName(HANDLE archive, const std::string &file_path, LCID locale) {
SFileSetLocale(locale);
if (SFileHasFile(archive, file_path.c_str())) {
return file_path;
}
// Replaced byte by byte rather than through WindowsifyFilePath: its filesystem::path
// re-encodes a name on Windows, and a lookup must hand StormLib the stored bytes
std::string backslashed = file_path;
std::replace(backslashed.begin(), backslashed.end(), '/', '\\');
if (backslashed != file_path && SFileHasFile(archive, backslashed.c_str())) {
return backslashed;
}
return file_path;
}

bool ArchivedFileMatches(HANDLE archive, HANDLE file, const fs::path &local_file,
std::string &match_reason) {
const DWORD archived_size = SFileGetFileSize(file, nullptr);
Expand Down
8 changes: 8 additions & 0 deletions src/mpq/query.h
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,14 @@ inline const std::vector<std::string> special_mpq_files = {"(listfile)", "(signa

bool FileExistsInArchiveForLocale(HANDLE archive, const std::string &file_path, LCID locale);

/// Returns the name the archive stores file_path under, looked up under locale
///
/// An MPQ normally stores paths with backslashes, and StormLib hashes / and \ as different
/// characters, so a path written with forward slashes misses. The path is tried as given
/// first, since an archive from another tool may store forward slashes itself, then with
/// every / turned into \. A path found in neither form comes back as given.
std::string StoredFileName(HANDLE archive, const std::string &file_path, LCID locale);

/// Reports whether the archived copy of local_file is byte-for-byte current
bool ArchivedFileMatches(HANDLE archive, HANDLE file, const std::filesystem::path &local_file,
std::string &match_reason);
Expand Down
16 changes: 9 additions & 7 deletions src/mpq/read.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

#include <memory>
#include <ostream>
#include <string>

#include <StormLib.h>

Expand All @@ -14,31 +15,32 @@ std::unique_ptr<char[]> ReadArchivedFile(HANDLE archive, const char *file_name,
unsigned int *file_size, LCID preferred_locale,
std::ostream &err) {
SFileSetLocale(preferred_locale);
if (!FileExistsInArchiveForLocale(archive, file_name, preferred_locale) &&
!FileExistsInArchiveForLocale(archive, file_name, default_locale)) {
const std::string stored_name = StoredFileName(archive, file_name, preferred_locale);
if (!FileExistsInArchiveForLocale(archive, stored_name, preferred_locale) &&
!FileExistsInArchiveForLocale(archive, stored_name, default_locale)) {
err << "[!] Failed: File doesn't exist"
<< PrettyPrintLocale(preferred_locale, " for locale ", true) << ": " << file_name
<< PrettyPrintLocale(preferred_locale, " for locale ", true) << ": " << stored_name
<< std::endl;
return nullptr;
}

HANDLE file;
if (!SFileOpenFileEx(archive, file_name, SFILE_OPEN_FROM_MPQ, &file)) {
err << "[!] Failed: File cannot be opened: " << file_name << std::endl;
if (!SFileOpenFileEx(archive, stored_name.c_str(), SFILE_OPEN_FROM_MPQ, &file)) {
err << "[!] Failed: File cannot be opened: " << stored_name << std::endl;
return nullptr;
}

*file_size = SFileGetFileSize(file, nullptr);
if (*file_size == SFILE_INVALID_SIZE) {
err << "[!] Failed: Invalid file size for: " << file_name << std::endl;
err << "[!] Failed: Invalid file size for: " << stored_name << std::endl;
SFileCloseFile(file);
return nullptr;
}

auto file_content = std::make_unique<char[]>(*file_size);
DWORD bytes_read;
if (!SFileReadFile(file, file_content.get(), *file_size, &bytes_read, nullptr)) {
err << "[!] Failed: Cannot read file contents for: " << file_name << std::endl;
err << "[!] Failed: Cannot read file contents for: " << stored_name << std::endl;
SFileCloseFile(file);
return nullptr;
}
Expand Down
14 changes: 7 additions & 7 deletions src/mpq/remove.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -13,19 +13,19 @@ namespace mpqcli {
int RemoveFile(HANDLE archive, const std::string &archive_file_path, LCID locale,
std::ostream &err) {
SFileSetLocale(locale);
err << "[-] Removing file" << PrettyPrintLocale(locale, " for locale ") << ": "
<< archive_file_path << std::endl;
const std::string stored_path = StoredFileName(archive, archive_file_path, locale);
err << "[-] Removing file" << PrettyPrintLocale(locale, " for locale ") << ": " << stored_path
<< std::endl;

if (!FileExistsInArchiveForLocale(archive, archive_file_path, locale)) {
if (!FileExistsInArchiveForLocale(archive, stored_path, locale)) {
err << "[!] Failed: File doesn't exist" << PrettyPrintLocale(locale, " for locale ", true)
<< ": " << archive_file_path << std::endl;
<< ": " << stored_path << std::endl;
return 1;
}

if (!SFileRemoveFile(archive, archive_file_path.c_str(), 0)) {
if (!SFileRemoveFile(archive, stored_path.c_str(), 0)) {
err << "[!] Failed: File cannot be removed"
<< PrettyPrintLocale(locale, " for locale ", true) << ": " << archive_file_path
<< std::endl;
<< PrettyPrintLocale(locale, " for locale ", true) << ": " << stored_path << std::endl;
return 1;
}

Expand Down
13 changes: 7 additions & 6 deletions src/mpq/rename.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -14,20 +14,21 @@ namespace mpqcli {
int RenameFile(HANDLE archive, const std::string &old_archive_file_path,
const std::string &new_archive_file_path, LCID locale, std::ostream &err) {
SFileSetLocale(locale);
const std::string old_stored_path = StoredFileName(archive, old_archive_file_path, locale);
const std::string new_stored_path = WindowsifyFilePath(new_archive_file_path);
err << "[~] Renaming file" << PrettyPrintLocale(locale, " for locale ") << ": "
<< old_archive_file_path << " -> " << new_stored_path << std::endl;
<< old_stored_path << " -> " << new_stored_path << std::endl;

if (!FileExistsInArchiveForLocale(archive, old_archive_file_path, locale)) {
if (!FileExistsInArchiveForLocale(archive, old_stored_path, locale)) {
err << "[!] Failed: File doesn't exist" << PrettyPrintLocale(locale, " for locale ", true)
<< ": " << old_archive_file_path << std::endl;
<< ": " << old_stored_path << std::endl;
return 1;
}

if (!SFileRenameFile(archive, old_archive_file_path.c_str(), new_stored_path.c_str())) {
if (!SFileRenameFile(archive, old_stored_path.c_str(), new_stored_path.c_str())) {
err << "[!] Failed: File cannot be renamed"
<< PrettyPrintLocale(locale, " for locale ", true) << ": " << old_archive_file_path
<< " -> " << new_stored_path << std::endl;
<< PrettyPrintLocale(locale, " for locale ", true) << ": " << old_stored_path << " -> "
<< new_stored_path << std::endl;
return 1;
}

Expand Down
4 changes: 1 addition & 3 deletions src/util/path.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,8 @@ std::string NormalizeFilePath(const fs::path &path) {
std::string file_path = path.u8string();
#ifndef _WIN32
std::replace(file_path.begin(), file_path.end(), '\\', '/');
return file_path;
#else
return file_path;
#endif
return file_path;
}

std::string WindowsifyFilePath(const fs::path &path) {
Expand Down
43 changes: 43 additions & 0 deletions test/fixtures/raw_archive.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
#ifndef RAW_ARCHIVE_H
#define RAW_ARCHIVE_H

#include <filesystem>
#include <stdexcept>
#include <string>
#include <utility>
#include <vector>

#include <StormLib.h>

namespace mpqcli::testing {

/// Writes an archive holding each name under its locale, through StormLib directly
///
/// mpqcli stores every path with backslashes, but StormLib stores a name exactly as given,
/// so this is how a test gets an archive another tool wrote with forward slashes. Each file
/// holds its own name as its content, so a read shows which entry it found. Throws
/// std::runtime_error when StormLib refuses, since that is a broken fixture.
inline void WriteRawArchive(const std::filesystem::path &path,
const std::vector<std::pair<std::string, LCID>> &entries) {
HANDLE archive = nullptr;
if (!SFileCreateArchive(path.string().c_str(), MPQ_CREATE_LISTFILE | MPQ_CREATE_ARCHIVE_V1, 16,
&archive)) {
throw std::runtime_error("WriteRawArchive: cannot create " + path.string());
}
for (const auto &[name, locale] : entries) {
const auto size = static_cast<DWORD>(name.size());
HANDLE file = nullptr;
if (!SFileCreateFile(archive, name.c_str(), 0, size, locale, 0, &file) ||
!SFileWriteFile(file, name.data(), size, 0) || !SFileFinishFile(file)) {
SFileCloseArchive(archive);
throw std::runtime_error("WriteRawArchive: cannot add " + name);
}
}
if (!SFileCloseArchive(archive)) {
throw std::runtime_error("WriteRawArchive: cannot close " + path.string());
}
}

} // namespace mpqcli::testing

#endif // RAW_ARCHIVE_H
16 changes: 16 additions & 0 deletions test/functional/test_extract.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -397,6 +397,22 @@ TEST_CASE("extract: a named nested file keeps its folder", "[extract]") {
REQUIRE(ReadFile(output_dir / "texts" / "cats.txt") == "This is a file about cats.\n");
}

TEST_CASE("extract: a named nested file given with forward slashes", "[extract]") {
SampleArchive sample;
AddNestedCats(sample);
const auto output_dir = sample.files.dir.Path() / "extracted_nested";

auto result = Run(mpqcli_binary, {"extract", "-o", output_dir.string(), sample.archive.string(),
"texts/cats.txt"});

REQUIRE(result.returncode == 0);
REQUIRE(result.stdout_output.empty());
REQUIRE(LinesToSet(result.stderr_output) ==
std::set<std::string>{"[*] Extracted: " + Native("texts\\cats.txt")});
REQUIRE(DirectoryEntries(output_dir) == std::set<std::string>{"texts"});
REQUIRE(ReadFile(output_dir / "texts" / "cats.txt") == "This is a file about cats.\n");
}

TEST_CASE("extract: a named nested file drops its folder with --flat", "[extract]") {
const auto flag = GENERATE(as<std::string>{}, "-j", "--flat");
CAPTURE(flag);
Expand Down
Loading