{"id":25401931,"url":"https://github.com/maxsafer/trash-tool","last_synced_at":"2025-04-12T08:59:21.170Z","repository":{"id":277668129,"uuid":"933145329","full_name":"Maxsafer/trash-tool","owner":"Maxsafer","description":"Linux trash command, adds a trash stage for files before deletion.","archived":false,"fork":false,"pushed_at":"2025-02-27T04:54:05.000Z","size":127,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-12T08:59:13.725Z","etag":null,"topics":["bash-script","linux-shell","macos"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Maxsafer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-15T08:56:57.000Z","updated_at":"2025-02-22T16:40:32.000Z","dependencies_parsed_at":"2025-02-15T10:22:19.844Z","dependency_job_id":"a6ed0cc0-49e9-4e41-9368-69ff84d5d4f7","html_url":"https://github.com/Maxsafer/trash-tool","commit_stats":null,"previous_names":["maxsafer/trash-tool"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Maxsafer%2Ftrash-tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Maxsafer%2Ftrash-tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Maxsafer%2Ftrash-tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Maxsafer%2Ftrash-tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Maxsafer","download_url":"https://codeload.github.com/Maxsafer/trash-tool/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248543861,"owners_count":21121838,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash-script","linux-shell","macos"],"created_at":"2025-02-16T01:20:48.169Z","updated_at":"2025-04-12T08:59:21.164Z","avatar_url":"https://github.com/Maxsafer.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Trash Tool (CLI Utility)\nThis tool is a Bash utility designed to manage files and directories by moving them to a designated \"trash can\" directory, allowing for recovery or permanent deletion at a later time. This utility mimics a recycle bin or trash functionality commonly found in graphical operating systems but is implemented for command-line environments. Below is a detailed high-level documentation of this tool, including its functionality and usage examples.\n\nI came up with this idea when I was working on a highly restrictive Linux environment. It works at the permission level you configure it to run at, meaning it is a mobile trash can configured and installed per user, located at ~/userdefinedpath.\n\n## Installation:\nNavigate to the desired installation path and run:\n```\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Maxsafer/trash-tool/refs/heads/main/installer.sh)\"\n```\nThis will create a new folder called `trash_tool` and it will add the following aliases `ts` and `trash`. If these are not recognized, manually source the displayed file.\n\nRunning this installer more than once will not mess with your previously trashed files, but moving the installation folder or renaming it will cause the aliases to break.\n\n## Overview:\n\nThe tool performs the following main functions:\n\n* Initializes a trash directory and associated metadata files if they do not exist.\n* Provides commands to list, recover, and permanently delete files from the trash.\n* Supports scheduling automatic trash emptying using cron jobs.\n* Offers a help menu to guide users on how to use the tool.\n\n## Initialization:\n\nThe script sets up a directory named trash_can in the same location as the script itself to store trashed files.\nIt creates a trash.json file to keep track of the original file paths and the date they were trashed.\n\n## Key Functionalities:\n\n### Listing Files:\n\n`-l` or `--list`: Lists files in the trash can. Supports optional recursive listing and filtering by text or regex.\n\n**Example:** `ts -l` lists all files, `trash -l -R` lists all files recursively, and `trash -l -s some-folder filter` filters the recursively listed trash selected folder by text or regex.\n\n### Recovering Files:\n\n`-r` or `--recover`: Recovers specified files from the trash can.\n\n`-d` or `--dictionary`: Displays the dictionary of trashed files, optionally filtered by text or regex.\n\n**Example:** `ts -r file1` recovers file1, `trash -r -d` displays the dictionary for all trashed files.\n\n### Emptying Trash:\n\n`-e` or `--empty`: Permanently deletes files from the trash can.\n\n`--confirm`: Empties the entire trash can.\n\n`--older [days]`: Deletes only files older than the specified number of days.\n\n**Example:** `ts -e file1` deletes file1, `trash -e --confirm` empties the entire trash can, `ts -e --older 30` deletes every file older than 30 days.\n\n### Cron Job Management:\n\n`-c` or `--cron`: Manages automated trash emptying via cron.\n\n`-p` or `--print`: Displays the current cron job related to trash.\n\n`-t` or `--time [days]`: Sets up automatic emptying of trash every N days.\n\n`-o` or `--older [days]`: Deletes files older than N days when emptying.\n\n**Example:** `ts -c -t 7` sets up a cron job to empty trash every 7 days, `trash --cron --time 7 --older 30` sets up a cron job to empty trash every 7 days that is older than 30 days.\n\n### Help:\n\n`-h` or `--help`: Displays the help menu with usage instructions.\n```\nTrash Tool v1.1\n \nUsage: trash [OPTION] SOURCE\nUsage: ts [OPTION] SOURCE\n \nTool documentation: https://github.com/Maxsafer/trash-tool\n \nArgument list:\n-h, --help            Display this help menu.\n-l, --list            List files inside the trash can.\n                      [Optional: Can include a text/regex filter]\n                          e.g.    trash -l [text/regex]\n   -R, --Recursive    Recursively list all items in the trash can.\n                      [Optional: Can include a text/regex filter]\n                          e.g.    trash -l -R [text/regex]\n   -s, --select       List a specific trashed file/folder recursively.\n                      [Optional: Can include a text/regex filter]\n                          e.g.    trash -l -s folder [text/regex]\n \n[no argument]         Move file(s)/folder(s) to the trash.\n                          e.g.    trash file1 file2 ...\n \n-r, --recover         Recover file(s)/folder(s) from the trash.\n                          e.g.    trash -r file1 file2 ...\n   -d, --dictionary   Display the dictionary of trashed files.\n                      [Optional: Can include a text/regex filter]\n                          e.g.    trash -r -d [text/regex]\n \n-e, --empty           Permanently delete file(s)/folder(s) from the trash.\n                          e.g.    trash -e file1 file2 ...\n   --confirm          Empty the entire trash can.\n                          e.g.    trash -e --confirm\n   --older [days]     Delete only files older than the specified days.\n                          e.g.    trash -e --older 30\n \n-c, --cron            Manage automated trash emptying via cron.\n   -p, --print        Display the current cron job related to trash.\n                          e.g.    trash -c -p\n   -t, --time [days]  Set up automatic emptying of trash every N days.\n                          e.g.    trash -c -t 7\n   -o, --older [days] Only delete files older than N days when emptying.\n                          e.g.    trash -c -t 7 -o 30\n```\n\n## Usage Examples:\n\nTo move a file to the trash: `trash file1` or `ts file1`\n\nTo list all files in the trash: `trash -l` or `ts -l`\n\nTo recover a file: `trash --recover file1` or `ts -r file1`\n\nTo permanently delete a file from the trash: `trash --empty file1` or `ts -e file1`\n\nTo set up a cron job to empty trash every 30 days: `trash --cron --time 30`\n\nTo display help: `trash -h`\n\n## Error Handling:\n\n* This tool checks for the existence of files and directories before attempting operations.\n* It provides feedback if a file does not exist or if an unknown argument is provided.\n\n## Dependencies:\n\n* It uses standard Unix utilities like ls, mv, rm, and crontab.\n\n\n## Future Development\n\n* Developed a [branch](https://github.com/Maxsafer/trash-tool/tree/freedtspec) compliant with [FreeDesktop.org](https://specifications.freedesktop.org/trash-spec/latest/) specification.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxsafer%2Ftrash-tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxsafer%2Ftrash-tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxsafer%2Ftrash-tool/lists"}