Update trash(1) man page for clarity, compatibility notes, and examples #362
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
When a file is trashed, it is moved to $XDG_DATA_HOME/Trash/files/ (typically ~/.local/share/Trash/files/) along with its metadata stored in $XDG_DATA_HOME/Trash/info/. The metadata preserves the original path, deletion timestamp, file permissions, and ownership information. The command handles several edge cases: files with identical names are renamed with numerical suffixes, symbolic links are moved without following them, files on different filesystems are copied then deleted, and files with special characters are preserved correctly. Unlike rm, trash provides safety features through file restoration using trash-restore, metadata preservation, and system directory protection. It integrates with desktop environments, allowing trashed files to be viewed and restored through file managers. Files can be permanently deleted using trash-empty when needed. While compatibility options (-r, -f, -i) are accepted, they have no effect since trash always processes files recursively and does not require confirmation or force flags.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Purpose of the Changes
This PR updates the trash man page to:
Clarify compatibility quirks with GNU rm options.
Improve documentation of metadata retention (e.g., original path, deletion date).
Add practical examples for edge cases (e.g., files starting with -).
Standardize cross-references and external links for consistency.
Key Changes
Compatibility Notes
Explicitly documented that -d, -f, -i, -r, and -R are retained only for GNU rm compatibility but have no functional effect. This prevents user confusion for those transitioning from rm to trash.
Metadata Documentation
Added details about retained metadata (original path, deletion date, permissions) to the DESCRIPTION section, aligning with the FreeDesktop.org Trash Specification.
Examples
Included examples for handling files with leading dashes (e.g., trash -- -foo), which addresses a common edge case.
Standardized example formatting for consistency.
Cross-References
Linked related commands (trash-list, trash-restore, etc.) in the SEE ALSO section.
Added a direct URL to the FreeDesktop.org Trash Specification for easy access.
Updated the bug report link to the current GitHub repository.
Typos and Formatting
Fixed minor formatting issues (e.g., consistent use of backticks for commands).
Improved grammar and readability in option descriptions.
Why These Changes Matter
User Experience: Users transitioning from rm will immediately understand why certain flags (e.g., -f) behave differently in trash.
Transparency: Explicitly documenting metadata retention helps users trust the tool’s behavior (e.g., knowing files can be fully restored).
Discoverability: The added examples and cross-references make the man page more actionable for new users.
Testing
Local Review: Generated and reviewed the man page locally with man ./trash.1 to ensure proper formatting.
Example Validation: Tested all commands in the EXAMPLES section to confirm they work as described (e.g., trash -- -foo).