{"id":13398319,"url":"https://github.com/srsudar/eg","last_synced_at":"2025-10-21T04:54:48.677Z","repository":{"id":28189251,"uuid":"31691072","full_name":"srsudar/eg","owner":"srsudar","description":"Useful examples at the command line.","archived":false,"fork":false,"pushed_at":"2025-02-06T16:56:22.000Z","size":1256,"stargazers_count":1956,"open_issues_count":15,"forks_count":109,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-10-20T08:45:51.643Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","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/srsudar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2015-03-05T02:16:03.000Z","updated_at":"2025-10-20T02:10:22.000Z","dependencies_parsed_at":"2023-01-14T08:19:33.198Z","dependency_job_id":"8e895edf-709e-43fb-adfa-a56b866fa070","html_url":"https://github.com/srsudar/eg","commit_stats":{"total_commits":324,"total_committers":29,"mean_commits":"11.172413793103448","dds":"0.23765432098765427","last_synced_commit":"cf0e53dda1791fc099686adc071d4e0609bcb887"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/srsudar/eg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srsudar%2Feg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srsudar%2Feg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srsudar%2Feg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srsudar%2Feg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/srsudar","download_url":"https://codeload.github.com/srsudar/eg/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srsudar%2Feg/sbom","scorecard":{"id":844273,"data":{"date":"2025-08-11","repo":{"name":"github.com/srsudar/eg","commit":"83e069c9e4f99b1052b69546726919a884138715"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.4,"checks":[{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":3,"reason":"Found 6/19 approved changesets -- score normalized to 3","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE.txt:0","Info: FSF or OSI recognized license: MIT License: LICENSE.txt:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 18 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-23T21:06:00.175Z","repository_id":28189251,"created_at":"2025-08-23T21:06:00.175Z","updated_at":"2025-08-23T21:06:00.175Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280207203,"owners_count":26290616,"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","status":"online","status_checked_at":"2025-10-21T02:00:06.614Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-07-30T19:00:22.668Z","updated_at":"2025-10-21T04:54:48.659Z","avatar_url":"https://github.com/srsudar.png","language":"Python","funding_links":[],"categories":["Python","others","\u003ca name=\"cheatsheet\"\u003e\u003c/a\u003eCommands cheatsheet and snippets"],"sub_categories":[],"readme":"# eg\n\n\u003e Useful examples at the command line.\n\n[![Build Status](https://travis-ci.org/srsudar/eg.svg?branch=master)](https://travis-ci.org/srsudar/eg)\n\n## Overview\n\n`eg` provides examples of common uses of command line tools.\n\nMan pages are great. How does `find` work, again? `man find` will tell you, but\nyou'll have to pore through all the flags and options just to figure out a\nbasic usage. And what about using `tar`? Even with the man pages `tar` is\n[famously inscrutable without the googling for examples](http://xkcd.com/1168/).\n\nNo more!\n\n`eg` will give you useful examples right at the command line. Think of it as a\ncompanion tool for `man`.\n\n\u003e `eg` comes from _exempli gratia_, and is pronounced like the letters: \"ee\ngee\".\n\n![eg Demo](./eg-demo.gif)\n\n\n## Installation\n\n### With `pip`\n\n```shell\npip install eg\n```\n\n### With `brew`\n\n```shell\nbrew install eg-examples\n```\n\n### Run from source\n\nClone the repo and create a symlink to `eg_exec.py`. Make sure the location you\nchoose for the symlink is on your path:\n\n\n```shell\ngit clone https://github.com/srsudar/eg ./\nln -s /absolute/path/to/eg-repo/eg_exec.py /usr/local/bin/eg\n```\n\n\u003e Note that the location of `eg_exec.py` changed in version 0.1.x in order to\nsupport Python 3 as well as 2. Old symlinks will print a message explaining the\nchange, but you'll have to update your links to point at the new location. Or\nyou can install with `pip` or `brew`.\n\n`eg` doesn't ship with a binary. Dependencies are very modest and should not\nrequire you to install anything (other than [pytest](https://docs.pytest.org) if\nyou want to run the tests).  If you find otherwise, open an issue.\n\n\n## Usage\n\n`eg \u003cprogram\u003e`\n\n`eg` takes an argument that is the name of a program for which it contains\nexamples.\n\n`eg find` will provide examples for the `find` command.\n\n`eg --list` will show all the commands for which `eg` has examples.\n\nThe complete usage statement, as shown by `eg --help`, is:\n\n```\neg [-h] [-v] [-f CONFIG_FILE] [-e EXAMPLES_DIR] [-c CUSTOM_DIR] [-p PAGER_CMD]\n   [-l] [--color] [-s] [--no-color] [program]\n```\n\n\n## How it Works\n\nFiles full of examples live in `examples/`. A naming convention is followed\nsuch that the file is the name of the tool with `.md`. E.g. the examples for\n`find` are in `find.md`.\n\n`eg find` will pipe the contents of `find.md` through `less` (although it tries\nto respect the `PAGER` environment variable).\n\n\n## Configuration and Extension\n\n`eg` works out of the box, no configuration required.\n\nIf you want to get fancy, however, `eg` can be fancy.\n\nFor example, maybe a team member always sends you bzipped tarballs and you can\nnever remember the flag for bzipping--why can't that guy just use gzip\nlike everybody else? You can create an example for untarring and unzipping\nbzipped tarballs, stick it in a file called `tar.md`, and tell `eg` where to\nfind it.\n\nThe way to think about what `eg` does is that it takes a program name, for\nexample `find`, and looks for files named `find.md` in the default and custom\ndirectories (including subdirectories). If it finds them, it pipes them through\n`less`, with the custom files at the top. Easy.\n\nThe default and custom directories can be specified at the command line like\nso:\n\n```shell\neg --examples-dir='the/default/dir' --custom-dir='my/fancy/dir' find\n```\n\nInstead of doing this every time, you can define a configuration file. It must\nbegin with a section called `eg-config` and can contain two keys: `custom-dir`\nand `examples-dir`. Here is an example of a valid config file:\n\n    [eg-config]\n    examples-dir = ~/examples-dir\n    custom-dir = ~/my/fancy/custom/dir\n\nThe config file is looked for first at `${XDG_CONFIG_HOME}/eg/egrc` and then at\n`~/.egrc`. You can also specify a different location at the command line like\nso:\n\n```shell\neg --config-file=myfile find\n```\n\n## Editing Your Custom Examples\n\nIf you want to edit one of your custom examples, you can edit the file directly\nor you can just use the `-e` or `--edit` flag.\n\nTo edit your `find` examples, for example, you could say:\n\n```shell\neg -e find\n```\n\nThis will dump you into an editor. The contents will be piped before the default\nexamples the next time you run `eg find`.\n\n## Formatting Output\n\n`eg` is highly customizable when it comes to output. You have three ways to try\nand customize what is piped out the pager, applied in this order:\n\n1. Color\n1. Squeezing out excess blank lines\n1. Regex-based substitutions\n\n### Color\n\n`eg` is colorful. The default colors were chosen to be pretty-ish while boring\nenough to not create problems for basic terminals. If you want to override\nthese colors, you can do so in the egrc in a `color` section.\n\nThings that can be colored are:\n\n* `pound`: pound sign before headings\n* `heading`: the text of headings\n* `code`: anything indented four spaces other than a leading `$`\n* `prompt`: a `$` that is indented four spaces\n* `backticks`: anything between two backticks\n\nValues passed to these options must be string literals. This allows escape\ncharacters to be inserted as needed. An egrc with heading text a nice burnt\norange might look like this:\n\n    [eg-config]\n    custom-dir = ~/my/fancy/custom/dir\n\n    [color]\n    heading = '\\x1b[38;5;172m'\n\nTo remove color altogether, for example if the color formatting is messing up\nyour output somehow, you can either pass the `--no-color` flag to `eg`, or you\ncan add an option to your egrc under the `eg-config` section like so:\n\n    [eg-config]\n    color = false\n\n\n### Squeezing Blank Lines\n\nThe example files use a lot of blank lines to try and be readable at a glance.\nNot everyone likes this many blank lines. If you hate all duplicate lines, you\ncan use your favorite pager to remove all duplicate commands, like:\n\n```\neg --pager-cmd 'less -sR' find\n```\n\nThis will use `less -sR` to page, which will format color correctly (`-R`) and\nremove all duplicate blank lines (`-s`).\n\n`eg` also provides its own custom squeezed output format, removing all blank\nlines within a single example and only putting duplicate blank lines between\nsections. This can be configured at the command line with `--squeeze` or in\nthe egrc with the `squeeze` option, like:\n\n    [eg-config]\n    squeeze = true\n\nRunning `eg --squeeze find` removes excess newlines like so:\n\n![Squeezed Output](./squeezed_output.png)\n\n\n### Regex Substitutions\n\nAdditional changes to the output can be accomplished with regular expressions\nand the egrc. Patterns and replacements are applied using Python's `re` module,\nso look to the [documentation](https://docs.python.org/2/library/re.html) for\nspecifics. Substitutions should be specified in the egrc as a list with the\nsyntax: `[pattern, replacement, compile_as_multiline]`. If\n`compile_as_multiline` is absent or `False`, the pattern will not be compiled\nas multiline, which affects the syntax expected by `re`. The `re.sub` method is\ncalled with the compiled pattern and `replacement`.\n\nSubstitutions must be named and must be in the `[substitutions]` section of the\negrc. For example, this would remove all the four-space indents beginning\nlines:\n\n    [substitutions]\n    remove-indents = ['^    ', '', True]\n\nThis powerful feature can be used to perform complex transformations, including\nsupport additional coloring of output beyond what is supported natively by\n`eg`. If you wish there was an option to remove or add blank lines, color\nsomething new, remove section symbols, etc, this is a good place to start.\n\nIf multiple substitutions are present, they are sorted by alphabetically by\nname before being applied.\n\n\n## Paging\n\nBy default, `eg` pages using `less -RMFXK`. The `-R` switch tells `less` to\ninterpret ANSI escape sequences like color rather than showing them raw. `-M`\ntells it to show line number information in the bottom of the screen. `-F` to\nautomatically quit if the entire example fits on the screen. `-X` tells it not\nto clear the screen. Finally, `-K` makes `less` exit in response to `Ctrl-C`.\n\nYou can specify a different pager using the `--pager-cmd` option at the command\nline or the `pager-cmd` option in the egrc. If specified in the egrc, the value\nmust be a string literal. For example, this egrc would use `cat` to page:\n\n    [eg-config]\n    pager-cmd = 'cat'\n\n`pydoc.pager()` does a lot of friendly error checking, so it might still be\nuseful in some situations. If you want to use `pydoc.pager()` to page, you can\npass the `pydoc.pager` as the `pager-cmd`.\n\n\n\n\n## Format and Content of Examples\n\nExample documents are written in [markdown](http://daringfireball.net/projects/markdown/syntax).\nDocuments in markdown are easily read at the command line as well as online.\nThey all follow the same basic format.\n\nThis section explains the format so that you better understand how to quickly\ngrok the examples.\n\nContributors should also pay close attention to these guidelines to keep\nexamples consistent.\n\n\n## Overview\n\nAnything indented four spaces or surrounded by backticks \\`like this\\` are\nmeant to be input or output at the command line. A single line indented four\nspaces is a user-entered command. If a block is indented four spaces, only the\nlines beginning with `$` are user-entered--anything else is output.\n\n\n### Name of the Command\n\nThe first section heading should be simply the name of the tool. It should be\nfollowed by the most rudimentary examples. Users that are familiar with the\ncommand but just forget the precise syntax should be able to see what they need\nwithout scrolling. Example commands should be as real-world as possible, with\nfile names and arguments as illustrative as possible. Examples for the `cp`\ncommand, for instance, might be:\n\n    cp original.txt copy.txt\n\nHere the `.txt` extensions indicate that these are file names, while the names\nthemselves make clear which is the already existing file and which will be the\nnewly created copy.\n\nThis section shouldn't show output and should not include the `$` to indicate\nthat we are at the command line.\n\n**This section should be a quick glance for users that know what the tool does,\nknow a basic usage is what they are trying to do, and are just looking for a\nreminder.**\n\n\n### Basic Usage\n\nNext a Basic Usage section explains the most basic usage without using real\nfile names. This section gives users that might not know the usual syntax a\nmore abstract example than the first section. It is intended to provide a more\nuseful explanation than the first entry in the man page, which typically shows\nall possible flags and arguments in a way that is not immediately obvious to\nnew users of the command. The SYNOPSIS section of the man page for `cp`, for\nexample, shows:\n\n    cp [-R [-H | -L | -P]] [-fi | -n] [-apvX] source_file ... target_directory\n\n**The Basic Usage is intended to provide less verbose, more immediately\npractical versions of the man page's SYNOPSIS section.**\n\nCommands and flags that will affect the behavior are shown as would be entered\nin the command line, while user-entered filenames and arguments that do not\nalter the command's behaviors are shown in `\u003c \u003e`. Examples in the Basic Usage\nsection for the `cp` command, for instance, might be:\n\n    cp -R \u003coriginal_directory\u003e \u003ccopied_directory\u003e\n\nIn this command the `cp -R` indicate the command and behavior and thus are not\ngiven in `\u003c \u003e`. Case-dependent components of the command, in this case the\ndirectory to be copied and the name of the copy, are surrounded with `\u003c \u003e`.\nEach is wrapped in separate `\u003c \u003e` to make clear that it is in fact two\ndistinct arguments.\n\n### Additional Sections\n\nSubsequent subsections can be added for common uses of the tools, as\nappropriate.\n\n### Formatting\n\nAlthough markdown is readable, it can still be tricky without syntax\nhighlighting. We use spacing to help the eye.\n\n1. All code snippets are followed by at two blank lines, unless overruled by 2.\n\n2. Each line beginning a section (i.e. the first character on the line is `#`)\nshould be preceded by exactly three lines.\n\n3. Files should end with two blank lines.\n\n4. Lines should not exceed 80 characters, unless to accommodate a necessarily\n   long command or long output.\n\n\n## Contributing\n\nAdditions of new tools and new or more useful examples are welcome. `eg` should\nbe something that people want to have on their machines. If it has a man page,\nit should be included in `eg`.\n\nPlease read the Format of Examples section and review existing example files to\nget a feel for how `eg` pages should be structured.\n\nIf you find yourself turning to the internet for the same command again and\nagain, consider adding it to the examples.\n\n`eg` examples do not intend to replace man pages! `man` is useful in its own\nright. `eg` should provide quick examples in practice. Do not list all the\nflags for the sake of listing them. Assume that users will have `man`\navailable.\n\n\n### Building and Running Tests\n\n`eg` depends only on standard libraries and Python 2.x/3.x, so building should\nbe a simple matter of cloning the repo and running the executable `eg/eg.py`.\n\n`eg` uses pytest for testing, so you'll have to have it installed to run tests.\nOnce you have it, run `py.test` from **the root directory of the repo**.\n\nTests should always be expected to pass. If they fail, please open an issue,\neven if only so that we can better elucidate `eg`'s dependencies.\n\n\n## Grace Hopper Approves\n\nAlias `eg` to `woman` for something that is like `man` but a little more\npractical:\n\n```shell\n$ alias woman=eg\n$ man find\n$ woman find\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrsudar%2Feg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsrsudar%2Feg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrsudar%2Feg/lists"}