{"id":19510309,"url":"https://github.com/maxbane/gitautoreadme","last_synced_at":"2026-05-14T18:02:00.639Z","repository":{"id":141201323,"uuid":"2008401","full_name":"maxbane/gitAutoReadme","owner":"maxbane","description":"A git pre-commit hook script that automagically extracts documentation from your source files into your README file.","archived":false,"fork":false,"pushed_at":"2011-07-07T18:16:22.000Z","size":108,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-04T23:49:25.362Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maxbane.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-07-06T19:25:19.000Z","updated_at":"2013-12-08T09:23:44.000Z","dependencies_parsed_at":"2023-03-13T10:34:47.665Z","dependency_job_id":null,"html_url":"https://github.com/maxbane/gitAutoReadme","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/maxbane/gitAutoReadme","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxbane%2FgitAutoReadme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxbane%2FgitAutoReadme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxbane%2FgitAutoReadme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxbane%2FgitAutoReadme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxbane","download_url":"https://codeload.github.com/maxbane/gitAutoReadme/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxbane%2FgitAutoReadme/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33037047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"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-11-10T23:15:29.286Z","updated_at":"2026-05-14T18:02:00.605Z","avatar_url":"https://github.com/maxbane.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"gitAutoReadme\n=============\n\n    Version 0.1.1\n\nA git pre-commit hook script that automagically extracts documentation from your\nsource files into your ``README`` file. This ``README`` file itself was\ngenerated from the ``gitAutoReadme.sh`` script, and serves as a working example. \n\nHow it works\n------------\n\n``gitAutoReadme.sh`` installs itself (either by a copy or a symbolic link) into\nyour working copy's ``.git/hooks`` directory, and creates an ``[autoreadme]``\nsection in ``.git/config``, where various options control how it behaves (see\n_Configuration_ below for more details).\n\nWhenever you commit a set of changes to your repository, ``gitAutoReadme.sh``\ngets invoked before the commit is finalized. It looks through a set of source\nfiles that you have specified for special **sentinel** lines, which you have\nalso specified, and which surround the blocks of text that should be\nautomatically extracted and placed into your ``README`` file. Through judicious\ndefinition and ordering of your sentinels, you can arrange for the contents of\nthe ``README`` file to be collected from many scattered parts of different\nsource files. It's all about the self-documenting source code, baby!\n\nPrerequisities\n--------------\n\nBesides ``git``, ``gitAutoReadme`` only depends on a few standard Unix tools\nbeing available: ``bash``, ``cp``, ``ln``, and ``sed``.\n\nInstallation\n------------\n\nSimply obtain a copy of ``gitAutoReadme.sh``, which may be located anywhere on\nyour system, for example in the working directory of your clone of\n``git@github.com:maxbane/gitAutoReadme.git``. Then, in an interactive shell,\nexecute:\n\n    $ ./gitAutoReadme.sh -i\n\nYou will be walked through an interactive installation process, which you may\ncancel at any time. You must answer a series of questions about such things as\nthe location of the git working copy you want to install to, the desired name of\nyour ``README`` file, which source files to extract documentation from, and what\nsentinel lines to look for. You will also be asked whether the pre-commit hook\nshould be installed by copying ``gitAutoReadme.sh`` into ``.git/hooks``, or by\ncreating a symbolic link. The advantage of the latter option is that any changes\nto ``gitAutoReadme.sh`` that you subsequently make (you hacker, you) or pull\ndown from upstream, will immediately take effect.\n\nConfiguration\n-------------\n\nAfter running the interactive installation, you will find a new ``[autoreadme]``\nsection in your ``.git/config`` file. It might look like this (depending on what\nyou entered during the installation):\n\n    [autoreadme]\n        readme = README.md\n        sourceglob = *.c\n        topsentinel = ^BEGIN README$\n        bottomsentinel = ^END README$\n        includesentinels = false\n\nYou can change these configuration options either by editing the config file\ndirectly, or by using the ``git config`` commad. For example, if you want to add\n``*.py`` to the set of source files that get searched for ``README`` content,\nyou can do this:\n\n    $ git config --add autoreadme.sourceglob '*.py'\n\nAnd the resulting config file will look like this:\n\n    [autoreadme]\n        readme = README.md\n        sourceglob = *.c\n        topsentinel = ^BEGIN README$\n        bottomsentinel = ^END README$\n        includesentinels = false\n        sourceglob = *.py\n\nThe meanings of the options are as follows:\n\n  - ``autoreadme.readme``: The name of the ``README`` file to generate.\n\n  - ``autoreadme.sourceglob``: Each ``sourceglob`` line adds a set of files\n  to be searched for sentinels. You can enter anything here that ``bash``'s glob\n  or brace expansion will turn into a list of files, relative to the top of your\n  working copy.\n\n  - ``autoreadme.topsentinel`` and ``autoreadme.bottomsentinel``: These\n  lines must always come in pairs, and the first ``topsentinel`` line in the\n  config file is associated with the first ``bottomsentinel`` line, the sencond\n  ``topsentinel`` with the second ``bottomsentinel``, and so on. Each pair uses\n  ``sed``-style regular expressions to describe which lines of a source file\n  should be matched as top and bottom sentinels. Everything between a pair of\n  associated top/bottom-sentinel lines is extracted and placed in the ``README``\n  file upon a commit. Sentinels are searched for, and any matching text\n  extracted, _in the order in which they appear in the config file_. You can\n  therefore use different top/bottom-sentinel pairs, arranged in a particular\n  order, to put text from all over your source files into your ``README`` in\n  whatever order you like.\n\n  - ``includesentinels``: If ``true``, the sentinel lines themselves (in\n  addition to the text between them) will be included in the ``README``.\n\nUsage\n-----\n\nOnce ``gitAutoReadme`` is installed on your project's working copy and\nconfigured to your liking, simply make commits as normal. ``gitAutoReadme`` will\nprint a line for each sentinel that it searches for, indicating whether or not\nit was found in any source file. For example, here's what it looks like when\nmaking a commit to ``gitAutoReadme``'s own repository:\n\n    $ git commit -am 'More docs, tweaks.'\n    gitAutoReadme: ^OVERVIEW=\\\"$ ... ^\\\"$ \u003e README.md\n    gitAutoReadme: ^USAGE=\\\"$ ... ^\\\"$ \u003e README.md\n    gitAutoReadme: ^LICENSE='$ ... ^'$ \u003e README.md\n    [master f20d76e] More docs, tweaks.\n     2 files changed, 208 insertions(+), 15 deletions(-)\n\n``gitAutoReadme`` clears your ``README`` file before populating it on each\ncommit, but first it makes a copy of the existing ``README`` with the ``.old``\nsuffix..\n    \nYou can manually bypass all pre-commit hooks, including ``gitAutoReadme``, by\nusing the ``--no-verify`` option of ``git commit.``\n\n\nAlternatives\n------------\n\nMany programming languages provide mechanisms for self-documenting source code,\ne.g., Java's javadoc comments, and Python's doc strings. There are also many\ntools, like Epydoc, for extracting such documentation from source and producing\nfull API docs. The design goals of ``gitAutoReadme`` differ from these in\nseveral ways:\n\n  - The focus is on generating a ``README`` file rather than full API docs,\n    though you certainly could use ``gitAutoReadme`` to include all of your API\n    documentation in the ``README``, if you wanted to.\n\n  - It is completely language-neutral and markup-neutral. It can be used to\n    include not just comment strings, but any kind of text from your source\n    files, including snippets of live code.\n\n  - It integrates seamlessly into your ``git``-based workflow, and is perfect\n    for keeping the ``README`` displayed on your project's github page always\n    current. You could even add some more pre-commit hooks of your own, which\n    together with ``gitAutoReadme`` might do some pretty complicated\n    programmatic ``README``-generation.\n\n``gitAutoReadme`` is also related to so-called _literate programming_ tools like\nSweave, which are generally much more complicated and powerful.\n``gitAutoReadme`` offers simplicity, and takes a complementary approach: you\nembed your documentation in your code, rather than embedding your code in your\ndocumentation.\n\nInvocation\n----------\n\n    gitAutoReadme.sh [ -h | -i | -u gitroot ]\n\nOnce installed to your working copy of a repository, you normally don't need to\ninvoke ``gitAutoReadme.sh`` itself, as that will be handled by a pre-commit hook.\nThe exceptions are:\n\n  - Initially installing ``gitAutoReadme`` on a working copy: \n\n        ./gitAutoReadme.sh -i\n\n    This process is interactive in the terminal, and is described in the\n    _Installation_ section of the documentation.\n\n  - Uninstalling ``gitAutoReadme`` from a working copy: \n\n        ./gitAutoReadme.sh -u /path/to/working/copy\n\n    This will remove the ``gitAutoReadme.sh`` link/copy in the given working\n    copy's ``.git/hooks`` directory, and remove the ``[autoreadme]`` section\n    from its ``.git/config`` file.\n\n  - Manually running ``gitAutoReadme`` to generate the resulting ``README`` file\n    without peforming a commit (this must be done from the top of your working\n    copy):\n\n        ./.git/hooks/gitAutoReadme.sh\n\n  - Finally, invoking ``./gitAutoReadme.sh -h`` prints this _Invocation_ section\n    of the documention to standard out and exits.\n\nLicense and Copyright\n---------------------\n\nCopyright 2011 by Max Bane. Distributed under the terms of the [Creative Commons\nAttribution 3.0 Unported license] [1].\n\n[1]: http://creativecommons.org/licenses/by/3.0/     \"CC BY 3.0\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxbane%2Fgitautoreadme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxbane%2Fgitautoreadme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxbane%2Fgitautoreadme/lists"}