{"id":15690096,"url":"https://github.com/cytopia/lsl","last_synced_at":"2025-05-07T23:21:54.750Z","repository":{"id":147859300,"uuid":"85801844","full_name":"cytopia/lsl","owner":"cytopia","description":"Colorful file labels for you terminal which are displayed in ls output.","archived":false,"fork":false,"pushed_at":"2017-03-22T08:28:56.000Z","size":991,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-31T15:09:21.068Z","etag":null,"topics":["command-line","label","labels","ls","tags"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cytopia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2017-03-22T08:11:36.000Z","updated_at":"2021-09-05T04:25:26.000Z","dependencies_parsed_at":"2023-05-27T17:30:27.539Z","dependency_job_id":null,"html_url":"https://github.com/cytopia/lsl","commit_stats":{"total_commits":2,"total_committers":1,"mean_commits":2.0,"dds":0.0,"last_synced_commit":"052dd038c70d13f93c1011322a38fc8bda2876af"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cytopia%2Flsl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cytopia%2Flsl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cytopia%2Flsl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cytopia%2Flsl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cytopia","download_url":"https://codeload.github.com/cytopia/lsl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252969048,"owners_count":21833402,"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":["command-line","label","labels","ls","tags"],"created_at":"2024-10-03T18:07:19.258Z","updated_at":"2025-05-07T23:21:54.722Z","avatar_url":"https://github.com/cytopia.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"ls with labels\n==============\n\n\u003e POC: Colorful file labels for you terminal which are displayed in `ls` output.\n\n**Abstract**  \nModern graphical file manager offer the ability to label or tag certain files\nor directories with the primary goal for simpler searches based on them.\n\nI personally work-cli only (least as much as possible) and therefore lacking\nthat feature. So I came up with something that I wanted to share here:\n\nMeet `lsl` - a proof of concept tool which tries to make labels work with your\nfavorite file listing tool. With it you can have labels shown in normal`ls`\noutput. The core is nothing more than a simple wrapper around the ls command\nmixed with some search and replace magic behind the scenes.\n\n\n**Demonstration**\n\n![lsl intro](img/lsl-intro.gif)\n\n---\n\n**Note**  \nThis is a proof-of-concept and still a work-in-progress project. Please do test it and submit any bugs you find. If you like this project and want it to continue, let me know by staring it.\n\n---\n\nInstallation\n------------\n```shell\n$ ./configure [--prefix=/usr/local]\n$ make\n$ sudo make install\n```\n\n\nQuickstart\n----------\n\nCreate two labels\n```shell\n$ lbl admin -a important\n$ lbl admin -a todo\n```\n\nAssign labels to files\n```shell\n$ lbl add important ~/tmp/rsync.txt\n$ lbl add todo ~/tmp/how-to-ec2.md\n```\n\nShow folder contents with `lsl.py` or `lsl.sh`\n\u003cpre\u003e\n$ lsl.py -l ~/tmp\ntotal 254084\n-rw-rw-r--  1 cytopia cytopia 260046848 Feb 26 16:26 debian-8.7.1-amd64-netinst.iso\n-rwxrwxr-x  1 cytopia cytopia      1813 Mar 18 21:20 how-to-ec2.md \u003cspan style=\"color:white; background-color:#0000ff;\"\u003e[ todo ]\u003c/span\u003e\n-rw-rw-r--  4 cytopia cytopia      4096 Mar 13 21:30 rsync.txt \u003cspan style=\"color:white; background-color:#ff0000;\"\u003e[ important ]\u003c/span\u003e\n-rw-rw-r--  1 cytopia cytopia         0 Mar 18 15:10 some thing with space\n\u003c/pre\u003e\nShow folder contents with `ls`\n```shell\n$ ls -l ~/tmp\ntotal 254084\n-rw-rw-r--  1 cytopia cytopia 260046848 Feb 26 16:26 debian-8.7.1-amd64-netinst.iso\n-rwxrwxr-x  1 cytopia cytopia      1813 Mar 18 21:20 how-to-ec2.md\n-rw-rw-r--  4 cytopia cytopia      4096 Mar 13 21:30 rsync.txt\n-rw-rw-r--  1 cytopia cytopia         0 Mar 18 15:10 some thing with space\n```\n\n\nAvailable Files\n---------------\n\nBinaries\n* `lsl.sh`: Bash wrapper for `ls` to show labels\n* `lsl.py`: Python wrapper for `ls` to show labels\n* `lbl`: Label manager (add, edit, remove, list, search and admin tasks)\n\nDatabase files\n* `label.lbl`: Text file defines the labels and their colors\n* `store.lbl`: Text file which holds the relation between files and labels\n\nBash completion\n* `lbl`:  Bash/ZSH completion for the Label manager\n\nIf you don't have python installed, use the bash wrapper. However the bash version is notably slower (\u003e10x) when showing folders with lots of files. So I recommend you stick to the python version.\n\n\nUsage: ls\n---------\n\nYou can Use it exactly as you can with ls. (see [man ls](https://linux.die.net/man/1/ls)):\n```shell\n$ lsl.py -al\n$ lsl.py --color=always /usr/bin -l -a\n$ lsl.py -l -a ~/Desktop\n$ lsl.py ~/.config --color=always --group-directories-first -al\n```\n\nFor your convenience, I suggest creating a bash/zsh alias. A few examples:\n```shell\n# Add this to you bash/zsh config file:\nalias lsl='lsl.py -l'\n\n# You can also add your favorite ls arguments\nalias lsl='lsl.py -l --color=always --group-directories-first'\n```\n\n\nUsage: Managing labels (`lbl`)\n------------------------------\n\n**[Label Manager Usage](doc/LABEL_MANAGER.md)**\n\nIn order to be able to have labels appear next to files listed with `lsl.py`\nor `lsl.sh` you will first have to do two things.\n\n1. Define labels (text and color)\n2. Assign available labels to files or directories.\n\nThe first one is a task you do not have to do very often, simply define your\nlabels as you would do on github.com for example. This is done via the label\nmanager admin commands (`lbl admin`).\n\nNow that you have available defined labels you can easily assign them to files\nand directories via the label manager. The label manager includes many subcommands\nwith which you can do various actions including, adding, editing, deleting and\nsearching.\n\nSearching is also a very extensive feature. You can search by various criterias\nsuch as: by name, by regex, by path and by created and modified date.\n\nSee **[Label Manager Usage](doc/LABEL_MANAGER.md)** for complete set of commands.\n\n\nBash/ZSH completion\n-------------------\n\nIf you are as lazy as I am, you probably do not always want to type the full commands, but rather tab-complete for quicker results.\n\nThe label manager comes with bash completion for all its arguments, just as you are used from git for example.\n\n\nTechnical info\n--------------\n\nIn case you wonder how this all works, here are some basic information.\nIf it might still be unclear let me know and I will expand this section.\n\n### Label definitions\nLabel names and their colors are stored in `~/.config/lsl/label.lbl` in plain\ntext in the following format:\n```\nLABEL:::::COLOR\n```\nThis file holds all your label definitions that can be assigned to files or\ndirectories via the label manager.\n\n\n### Label database\nLabel assignments are stored in `~/.config/lsl/store.lbl` in plain text in the\nfollowing format:\n```\nPATH:::::LABEL:::::COLOR:::::CREATED:::::MODIFIED\n```\nPlain text is chosen so that it is easy for others to write their own script\nand be able to parse this file as needed. As well as to make it easier to\napply regex searches against this file.\n\nPlaintext makes it also possible to quickly search and replace some parts\nif you want to work manually on that file.\n\n### ls wrapper\n\n`lsl.py` and `lsl.sh` are just wrapper scripts around the actual `ls` command.\nAll they do is\n\n* issue the ls commaND supplied by the user\n* Extract the files from the output\n* Compare the files against the label database and add labels on match to the output\n\nThat's it, nothing magical.\n\n\n### Label manager\n\nThe label manager is a simple shell script that will edit `~/.config/lbl/store.lbl`\nfor you. You could also edit that file manually.\n\nThe label manager's task can be split into 4 major subtasks\n* Create global useable labels\n* Attach/remove labels on files and directories\n* Search labelled files by various criterias\n* Fix label database\n\n\n\nFrequently Asked Questions\n--------------------------\n\n**Where are my ls colors?**\n\nIn order to get your ls colors back, you will need to parse `--color=always` to `lsl.py` or `lsl.sh`.\n`--color=auto` does not work within scripts, so it must be forced.\n\nCurrent issues\n--------------\n\nThis software is far away from stable with a couple of known bugs that are being worked on. Some of them are:\n\n\n### Intended bevior\n* Labels will **only be shown in long output** (`-l`)\n\n### Actual bugs\n* Labels won't be shown for directories when using `--classify`|`-F`\n* Labels won't be shown for directories when using `--indicator-style`|`-p`\n* Labels won't be shown when using `--inode`|`-o`\n* Labels won't be shown when using `-g`\n* Labels won't be shown when using `--no-group`|`-G`\n* Labels won't be shown when using `-o`\n* Labels won't be shown when using `-Q`\n* Labels won't be shown when using `-x`\n* Labels won't be shown on symlinks when output is like: `file -\u003e realfile`\n\n\nBrainstorm ideas\n----------------\n\nThere is a whole page for **[Ideas](doc/IDEAS.md)**\n\n\nLicense\n-------\nLsl is released under the terms of the MIT license. See [LICENSE](LICENSE.md) for more\ninformation or see https://opensource.org/licenses/MIT.\n\n\nContribute\n----------\n\nThis is an open-source project I do in my spare time which is absolutely free to use for anybody. If this tool makes your life easier consider contributing to it.\n\nThere are a couple of things how you can contribute:\n\n1. Let me know you like it by pressing the star button. Everyone is honored by *likes*. Seeing a good amount of people interested in this project, I can put in my effort accordingly.\n2. Try it out, play with it and if it is useful stick with it. Consider yourself a tester and please do report any bugs you encounter, so they can be put onto the roadmap. \n3. You have an awesome feature in mind that should be integrated, please do report it.\n4. You have an awesome feature in mind that should be integrated and you are a programmer, please fork this repository and try to implement it. Github is all about giving code to the community.\n5. You know about graphics? Submit a logo.\n6. This tool is really making you happy, consider donating a beer:\n\n\nAnd btw, if you find a typo, that's a nice thing too to report ;-)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcytopia%2Flsl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcytopia%2Flsl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcytopia%2Flsl/lists"}