linux-commands-guide 2.1.1__tar.gz → 2.2.1__tar.gz

linux_commands_guide-2.2.1/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+## 2.2.1 — 2026-10-13
+
+### Fixed
+- Source packaging uses project files only. No CLI or catalogue changes.
+
+## 2.2.0 — 2026-10-13
+
+### Added
+- Beginner quick/explained views, grouped categories, direct basic-command references and additional tools.
+- Ten bilingual terminal lessons and five fixture-based practice plans with opt-in hints/solutions.
+- Isolated user installer (`install.sh`), dry-run, guarded managed upgrades and offline wheelhouse support.
+- Content/contribution/compatibility/release guides, issue templates and generated README catalogue.
+- 114 command references, preserving the original examples.
+
+### Changed
+- Validated JSON catalogue and immutable models replace the Python content wrappers; existing CLI/shim entries remain.
+- Stream-local shellcolorize presentation removes import-time ANSI and global color mutation.
+- A tool plus `-s` now searches that tool; multiword searches require all words, ignoring accents/case.
+- Narrow terminals use stacked descriptions. Quick/explained views select at most eight examples.
+- CI checks minimum/published shellcolorize and an installed wheel outside the checkout.
+- English-only README and a real terminal demo alternating English and Spanish output.
+
+### Fixed
+- grep directory include/exclude examples now use recursion.
+- chmod guidance accounts for umask; regex examples identify their dialect.
+- find/xargs filename recipes use NUL separators; xargs -I receives one filename per line.
+- Dangerous examples include effects and warnings; SSH/TLS bypasses are not routine fixes.
+
+
+## 2.1.1
+
+### Changed
+- Project metadata: author and project links now point to github.com/serber-info.
+- No functional changes.
+
+## 2.1.0
+
+### Fixed (content)
+- `regex`: `word{3}`, `word*`, `word+` and `word?` were described as repeating the whole word; a quantifier only
+  applies to the previous item. Now `(word){3}`, `(word){2,5}`, `a*`, `a+` and `colou?r`.
+- `lxc`: `lxc-config -n … -s storage|network|security`, `lxc-attach -f /path` and `lxc-restart` do not exist or
+  do something else. The tool now covers create, start/stop/reboot, attach, console, info, freeze, copy,
+  snapshot, destroy and checkconfig.
+- `chown --from` had the wrong syntax (`--from=old_user new_user file`).
+- `cat` listed `bat` options (`-r`, `--theme`, `--paging`, `-L`) as if they were `cat` options.
+- `rsync` examples without `-a` did not recurse (`--delete`, `--exclude`, `--dry-run`…).
+- `xargs -P 4 python3` passed many files to one process; now `-n 1 -P 4`.
+- `iptables` uses `-m conntrack --ctstate` instead of the deprecated `-m state`.
+- Clarified `ifconfig add` (IPv6), tmux split directions and netcat variants (`-p`, `-e`).
+
+### Fixed
+- README install command (`pip install linux-commands-guide`), badges and clone folder.
+- Missing LICENSE file (MIT, as declared).
+- Colors were written into pipes and files; output is plain when piped or when `NO_COLOR` is set.
+- Header boxes were two characters too wide.
+- `lh tool | head` printed a BrokenPipeError traceback.
+
+### Added
+- Language is picked from the locale (`es_*` → Spanish, anything else → English); `--lang` still forces it.
+- Search matches both the Spanish and the English descriptions.
+- `lh --version` and `python -m guia_linux`.
+- Test suite (content checks for all 51 tools) and GitHub Actions CI.
+
+### Removed
+- The legacy top-level `tools/` directory (v1 code, no longer used).
+
+## 2.0.1
+
+- Visual redesign: clean box headers, ANSI-aware alignment.
+
+## 2.0.0
+
+- Bilingual, search, 51 tools, pip-installable.

linux_commands_guide-2.2.1/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing / Contribuir
+
+Help beginners understand a task, not just memorize an option. Small contributions are welcome:
+translations, corrected examples, clearer warnings and new beginner references.
+
+## Before changing content
+
+1. Check whether the command already exists inside a grouped reference (`system`, `cat`, `ssh`).
+2. Read the [content guide](docs/content-guide.md) and the installed tool's manual.
+3. Keep Spanish and English equally useful, and cite primary documentation.
+4. Describe effects and prerequisites. Never recommend bypassing permissions, TLS or host-key
+   checks as a routine fix. Do not suggest `chmod 777` as a troubleshooting shortcut.
+5. Test only safe examples with temporary fixtures. Never run the whole catalogue.
+
+## Local checks
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+python -m scripts.update_catalog_docs
+ruff check .
+pytest -q
+```
+
+Adding `guia_linux/content/tools/<name>.json` automatically registers it. No handwritten Python
+wrapper or registry is needed. The README table is generated; CI checks it is up to date.
+
+A PR should state the learner's task, official source, compatibility, effects and verification.
+Do not include real credentials, customer data, private infrastructure or personal paths.
+
+## Useful issue labels
+
+Suggested labels for maintainers: `content`, `beginner`, `translation`, `bug`, `good first issue`.
+They are suggestions, not automatically created GitHub labels.
+
+## Scope
+
+Keep runtime offline and small. New services, telemetry, automatic command execution and access to
+personal files are not part of this project. A fixture exercise is not a general shell runner.
+Internal Python catalogue modules changed in this refactor; the supported public surface is `lh`,
+`python -m guia_linux`, `helper.py`, and the lazy `guia_linux.main()` entry.

linux_commands_guide-2.2.1/MANIFEST.in

@@ -0,0 +1,8 @@
+include install.sh
+include helper.py
+include CONTRIBUTING.md
+include CHANGELOG.md
+recursive-include scripts *.py
+recursive-include docs *.md *.gif *.cast
+recursive-include tests *.py
+recursive-include tests *.json

linux_commands_guide-2.2.1/PKG-INFO

@@ -0,0 +1,337 @@
+Metadata-Version: 2.4
+Name: linux-commands-guide
+Version: 2.2.1
+Summary: Learn Linux in your terminal: bilingual quick reference, lessons and safe practice plans
+Author: Sergio Berruetta
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/serber-info/linux-commands-guide
+Project-URL: Bug Tracker, https://github.com/serber-info/linux-commands-guide/issues
+Project-URL: Source Code, https://github.com/serber-info/linux-commands-guide
+Project-URL: Changelog, https://github.com/serber-info/linux-commands-guide/blob/main/CHANGELOG.md
+Keywords: linux,cheatsheet,commands,reference,sysadmin,bilingual,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Natural Language :: English
+Classifier: Natural Language :: Spanish
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: shellcolorize>=1.1.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# linux-commands-guide — `lh`
+
+[![CI](https://github.com/serber-info/linux-commands-guide/actions/workflows/ci.yml/badge.svg)](https://github.com/serber-info/linux-commands-guide/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/linux-commands-guide.svg)](https://badge.fury.io/py/linux-commands-guide)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+**Learn Linux from your terminal. Find a command, understand it, then practice.**
+
+`lh` is an offline Spanish/English quick reference for beginners, with advanced entries when you
+need them. It displays examples; **it never executes them**. No account, telemetry or network
+connection is needed after installation. It also works over SSH.
+
+<p align="center">
+  <img src="docs/demo.gif" alt="Real terminal demo: quick reference, search, explanations, lessons and practice, alternating English and Spanish" width="1000">
+</p>
+
+*Real CLI output. [Reproduce this recording](docs/demo.md).*
+
+## Start here
+
+```bash
+lh ls --quick                 # A short reference
+lh grep --explain             # Explanation and sources
+lh learn pipes                # Understand pipelines
+lh practice grep              # A challenge with sample data
+lh practice grep --hint       # Hint
+lh practice grep --solution   # Solution
+```
+
+Language follows your locale. Use `--lang es` or `--lang en` to choose explicitly.
+
+## Install
+
+### From a checkout: one command
+
+Requires Linux, Python 3.9+ with `venv`/pip, and Internet access during installation.
+
+```bash
+git clone https://github.com/serber-info/linux-commands-guide.git
+cd linux-commands-guide
+./install.sh
+```
+
+The installer creates an isolated environment in `~/.local/share/linux-commands-guide/venv`
+and a launcher in `~/.local/bin/lh`. **Do not use sudo.** It does not change system Python or shell
+configuration, and refuses to overwrite an unrelated `lh` or reuse an unknown installation directory.
+If `~/.local/bin` is not on PATH, it prints the command to enable it for your current terminal.
+On Debian/Ubuntu you may need the distribution's `python3-venv` package first.
+
+If installation fails, it reports the error and preserves files for inspection instead of deleting them.
+
+```bash
+./install.sh --dry-run         # Inspect paths without writes
+./install.sh --upgrade         # Update a managed install
+./install.sh --help            # Custom paths and offline wheelhouse
+```
+
+### Published version
+
+If you already use [pipx](https://pipx.pypa.io/stable/), the published release can be installed with:
+
+```bash
+pipx install linux-commands-guide
+```
+
+Version 2.2.0 includes the beginner references, lessons, practice plans and installer.
+
+For an existing virtual environment:
+
+```bash
+python -m pip install linux-commands-guide
+```
+
+`shellcolorize` is the author's separate project, published on PyPI, and remains the color dependency.
+Its repository does not need to be cloned for installation.
+
+## Reference
+
+```bash
+lh awk                            # Full reference
+lh ls --quick                     # Up to 8 curated examples
+lh grep --explain                 # Curated examples, explanation, notes and sources
+lh -s 'disk space'                # Search both languages
+lh grep -s recursive              # Search only grep
+lh list                           # Browse categories
+lh list --category files          # Filter a category
+lh --lang en ssh                  # Force English
+lh --help
+lh --version
+python -m guia_linux awk           # Same CLI
+python helper.py awk              # Legacy shim remains
+```
+
+Search is case/accent-insensitive and requires every query word to match an entry's text, tool
+summary or curated task keywords. It is local, not AI or natural-language reasoning. Use a few specific words.
+
+Long references can be piped into `less`. `NO_COLOR=1` disables color; redirected output is plain
+unless you explicitly set `FORCE_COLOR`. Commands are never reflowed, so copying preserves their
+syntax; descriptions stack on narrow terminals.
+
+```bash
+lh tar | less
+NO_COLOR=1 lh grep
+```
+
+`--explain` focuses on selected examples, not every advanced option. The most detailed explanations
+are in foundational entries; advanced entries retain notes, effect warnings and source links.
+`--explain` is not a replacement for the complete manual of each program.
+
+## Learn and practice
+
+```bash
+lh learn
+lh practice
+```
+
+Suggested route:
+
+1. `navigation` — paths, directories
+2. `quoting` — quotes and arguments
+3. `globs` — filename globs versus regex
+4. `pipes` — stdin, stdout and stderr
+5. `redirections` — input/output and overwrite risk
+6. `exit-status` — exit codes, `&&` and `||`
+7. `environment`, `permissions`, `processes`, `help`
+
+Practices currently cover `grep`, `pipes`, `navigation`, `wc` and `regex`. They print fixture setup,
+a challenge and expected output; hints and solutions are opt-in. **No commands run and no files
+are created by lh.** If you copy the setup, it creates a fresh temporary directory. Use only that
+directory; root is not required. There is no automatic assessment or cleanup of your files.
+
+Practices are guided: you run commands and compare results. `lh` does not inspect your documents,
+execute your input or store your progress.
+
+## Safety and compatibility
+
+- Examples may **write, delete, change system state, generate traffic or expose sensitive data**.
+  Such effects are labeled. An unlabelled reference is not a guarantee of safety.
+- Never copy placeholders such as `<file>` literally. Replace them, omit the angle brackets and
+  quote paths with spaces. Do not copy shell prompts (`$`/`#`) as commands.
+- Read notes before using `sudo`, destructive options, recursive permissions or network changes.
+- Scan only systems you own or have permission to test.
+- The reference primarily covers GNU/Linux. Shell builtins, regex engines, netcat variants,
+  distributions and installed versions can differ. systemd entries require systemd.
+- Structural tests cover all content. Behavioral tests cover **selected** safe examples and practice
+  fixtures, not every command or every Linux distribution.
+
+See [compatibility](docs/compatibility.md) and [learning path](docs/learning-path.md).
+
+## Available references
+
+<!-- BEGIN GENERATED CATALOG -->
+
+114 references. Categories and aliases are available through `lh list`.
+
+| Tool | Description | Category |
+|------|-------------|----------|
+| `apropos` | Find manuals by topic | basics |
+| `apt` | Packages on Debian/Ubuntu | system |
+| `awk` | Column-based text processing | text |
+| `bat` | Read files with syntax highlighting | files |
+| `bg` | Resume jobs in the background | processes |
+| `cat` | Display and concatenate file contents | files |
+| `cd` | Change to the specified directory | basics |
+| `chmod` | Change file and directory permissions | files |
+| `chown` | Change file owner and group | files |
+| `command` | Check command resolution | basics |
+| `cp` | Copy a file | files |
+| `crontab` | Periodic task scheduling | system |
+| `curl` | Transfer data with URLs | network |
+| `cut` | Extract sections from each line | text |
+| `date` | Show current date and time | system |
+| `descriptors` | stdin, stdout and stderr redirections | shell |
+| `df` | Display disk space usage | files |
+| `diff` | Compare text files | files |
+| `dig` | Query DNS records | network |
+| `dirs` | Show the directory stack | shell |
+| `dnf` | Packages on compatible Fedora/RHEL systems | system |
+| `docker` | Docker container management | advanced |
+| `du` | Display directory space usage | files |
+| `echo` | Display text or variables | text |
+| `env` | Inspect or pass environment variables | shell |
+| `export` | Pass variables to child processes | shell |
+| `fd` | Find files with fd | files |
+| `fg` | Bring jobs to the foreground | processes |
+| `file` | Identify file types | files |
+| `find` | Search for files and directories | files |
+| `firewall-cmd` | Manage the firewalld firewall | advanced |
+| `free` | Display system memory usage | processes |
+| `fzf` | Select text interactively | shell |
+| `getent` | Query system name resolution | network |
+| `git` | Version control with Git | development |
+| `grep` | Search for patterns in files | text |
+| `gzip` | Compress individual files | files |
+| `head` | Display the beginning of a file | text |
+| `help` | Help for Bash builtins | basics |
+| `history` | Inspect your shell history | shell |
+| `hostname` | Show or set the hostname | system |
+| `htop` | Interactive process monitor | processes |
+| `id` | Show UID, GID and groups of current user | system |
+| `ifconfig` | Network interface configuration (legacy) | network |
+| `ip` | Modern network interface and routing management | network |
+| `iptables` | Kernel firewall rule management | advanced |
+| `jobs` | Inspect jobs in your shell | processes |
+| `journalctl` | Read systemd logs | system |
+| `jq` | Command-line JSON processor | text |
+| `kill` | Send signals to processes | processes |
+| `less` | Display file contents interactively | files |
+| `ln` | Create a symbolic link | files |
+| `locate` | Find files using the locate database | files |
+| `logs` | Important log file paths in Linux | system |
+| `ls` | List the current directory contents | basics |
+| `lsblk` | List block devices | files |
+| `lsof` | List open files by processes | processes |
+| `lxc` | LXC container management | advanced |
+| `man` | Read command manuals | basics |
+| `mkdir` | Create a new directory | files |
+| `more` | Display file contents page by page | files |
+| `mv` | Move or rename a file or directory | files |
+| `nano` | Edit files in the terminal | files |
+| `nc` | TCP/IP Swiss army knife | network |
+| `ncdu` | Explore disk usage interactively | files |
+| `netstat` | Network connection statistics | network |
+| `nl` | Display file contents with line numbers | files |
+| `nmap` | Network and port scanner | advanced |
+| `pacman` | Packages on Arch-based systems | system |
+| `pgrep` | Find PIDs by name | processes |
+| `ping` | Check ICMP responses | network |
+| `popd` | Return to the previously saved directory | shell |
+| `printf` | Print predictably formatted text | text |
+| `ps` | Information about running processes | processes |
+| `pushd` | Save current directory and switch to the given one | shell |
+| `pwd` | Print the current working directory | basics |
+| `readlink` | Inspect symbolic links | files |
+| `realpath` | Resolve absolute paths | files |
+| `regex` | Regex search patterns | text |
+| `rg` | Search text with ripgrep | text |
+| `rm` | Remove a file | files |
+| `rsync` | Efficient file synchronization | files |
+| `scp` | Secure file copy over SSH | files |
+| `sed` | Stream text editor | text |
+| `sha256sum` | Check integrity with SHA-256 | files |
+| `shortcuts` | Bash/zsh keyboard shortcuts | basics |
+| `sort` | Sort lines of text | text |
+| `ss` | Socket statistics (replaces netstat) | network |
+| `ssh` | Secure Shell client | network |
+| `stat` | Show file details (timestamps, permissions) | files |
+| `sudo` | Understand and inspect privileges | system |
+| `system` | Navigation, files and system management | basics |
+| `systemctl` | Manage services with systemd | system |
+| `tail` | Display the end of a file | text |
+| `tar` | File archiving and compression | files |
+| `tee` | Read stdin and write to stdout and files | text |
+| `timeout` | Limit a command’s duration | processes |
+| `tmux` | Terminal multiplexer | shell |
+| `top` | Real-time process monitor | processes |
+| `touch` | Create an empty file or update its timestamp | files |
+| `tr` | Translate or delete characters | text |
+| `tree` | Display directories as a tree | files |
+| `type` | Identify commands, aliases and functions | basics |
+| `umask` | Understand new-file permissions | shell |
+| `uname` | System and kernel information | system |
+| `uniq` | Filter adjacent duplicate lines | text |
+| `unzip` | Inspect and extract ZIP archives | files |
+| `uptime` | Show how long the system has been running | system |
+| `vim` | Modal terminal text editor | shell |
+| `watch` | Execute a command periodically | processes |
+| `wc` | Count lines, words and bytes | text |
+| `whoami` | Show the current user | system |
+| `xargs` | Build and execute commands from stdin | text |
+| `zip` | Create ZIP archives | files |
+
+<!-- END GENERATED CATALOG -->
+
+## Development
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+ruff check .
+python -m scripts.update_catalog_docs --check
+pytest -q
+python -m build
+```
+
+Content lives in validated bilingual JSON under `guia_linux/content/`, not in executable Python or
+ANSI-colored strings. References can share example IDs without duplicating definitions.
+
+- `catalog.py` loads/validates content and handles lookup/search.
+- `render.py` presents it using stream-local `shellcolorize` colors, without global color mutation.
+- `learning.py` displays lessons and practice plans without executing commands.
+- `cli.py` parses requests; `models.py` holds immutable reference data.
+
+The CI tests the declared minimum and published `shellcolorize` versions, builds a wheel and
+checks installation outside the checkout. There is no automatic publication.
+
+## Contribute
+
+Found an incorrect example or confusing explanation? Open an issue; please remove private paths,
+credentials and personal information from output. New contributors can improve a translation,
+add a tested beginner example or clarify an error message.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the [content guide](docs/content-guide.md).
+For releases, see the [release checklist](docs/releasing.md). The [demo](docs/demo.gif) shows the
+current beginner journey with real terminal output; its [recording](docs/demo.cast) is also included.
+
+## License
+
+[MIT](LICENSE). [Changelog](CHANGELOG.md).