{"id":13896238,"url":"https://github.com/luvit/lit","last_synced_at":"2025-07-17T12:31:21.069Z","repository":{"id":23608776,"uuid":"26977863","full_name":"luvit/lit","owner":"luvit","description":"Toolkit for developing, sharing, and running luvit/lua programs and libraries.","archived":false,"fork":false,"pushed_at":"2025-05-25T00:48:48.000Z","size":3358,"stargazers_count":260,"open_issues_count":45,"forks_count":64,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-06-04T10:21:33.179Z","etag":null,"topics":["hacktoberfest","lua","luvit","package-manager"],"latest_commit_sha":null,"homepage":"http://lit.luvit.io/","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luvit.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}},"created_at":"2014-11-21T21:05:25.000Z","updated_at":"2025-05-25T00:48:52.000Z","dependencies_parsed_at":"2025-02-07T13:30:52.042Z","dependency_job_id":"796145bb-7021-42ce-862d-f0d6b0fa10d5","html_url":"https://github.com/luvit/lit","commit_stats":null,"previous_names":[],"tags_count":134,"template":false,"template_full_name":null,"purl":"pkg:github/luvit/lit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luvit%2Flit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luvit%2Flit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luvit%2Flit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luvit%2Flit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luvit","download_url":"https://codeload.github.com/luvit/lit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luvit%2Flit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265606635,"owners_count":23796973,"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":["hacktoberfest","lua","luvit","package-manager"],"created_at":"2024-08-06T18:02:45.818Z","updated_at":"2025-07-17T12:31:20.744Z","avatar_url":"https://github.com/luvit.png","language":"Lua","readme":"# Luvit Invention Toolkit\n\nLit is a toolkit designed to make working in the new [luvit][] 2.0 ecosystem\neasy and even fun.\n\n - Lit powers the central repository at `wss://lit.luvit.io/`.\n - Lit is used to publish new packages to the central repository.\n - Lit is used to download and install dependencies into your local tree.\n - Lit can be used to compile [luvi][] apps from folders or zip files into\n   self-executing binaries.\n\nLit is also a luvi app and library itself and bootstraps fairly easily.\n\n## Installing Lit\n\nIn most cases, you just want to install lit as quickly as possible, possibly\nin a `Makefile` or `make.bat` in your own library or app.\n\nWe maintain several [binary releases of\nluvi](https://github.com/luvit/luvi/releases) to ease bootstrapping of lit and\nluvit apps.\n\nThe following platforms are supported:\n\n - Windows (amd64)\n - FreeBSD 10.1 (amd64)\n - Raspberry PI (armv6)\n - Raspberry PI 2 (armv7)\n - Ubuntu 14.04 (x86_64)\n - Ubuntu 14.04 (i686)\n - OSX Yosemite (x86_64)\n\nOn unix, download the [install script](./get-lit.sh) and pipe to `sh`:\n\n```sh\ncurl -L https://github.com/luvit/lit/raw/master/get-lit.sh | sh\n```\n\nIf you're on Windows, We've thought of you as well.  Simply download and run\nthe [powershell script](./get-lit.ps1).\n\nIn `cmd.exe` run:\n\n```batch\nPowerShell -NoProfile -ExecutionPolicy unrestricted -Command \"[Net.ServicePointManager]::SecurityProtocol = 'Tls12'; iex ((new-object net.webclient).DownloadString('https://github.com/luvit/lit/raw/master/get-lit.ps1'))\"\n```\n\nOr directly in powershell, run:\n\n```powershell\n[Net.ServicePointManager]::SecurityProtocol = 'Tls12'\niex ((new-object net.webclient).DownloadString('https://github.com/luvit/lit/raw/master/get-lit.ps1'))\n```\n\nBoth these scripts will attempt to download a pre-compiled [luvi][] binary and\nthe source to lit as a zip file.  Then using the zip capabilities in luvi and\nlit, it will build itself using the zip file as both code and input data.\n\nWhen done, you will have a `lit` or `lit.exe` executable in your directory\nthat you can put somewhere in your path to install globally.\n\n#### Building From Source\n\nIf the pre-built luvi binaries don't work on your machine, you can always build\n[luvi from source](https://github.com/luvit/luvi#building-from-source).\n\nOnce you have luvi, building lit is simple:\n\n```sh\n\u003e curl -L https://lit.luvit.io/packages/luvit/lit/latest.zip \u003e lit.zip\n\u003e luvi lit.zip -- make lit.zip\n```\n\nOr you can clone lit from git and use the Makefile which will do the same thing\nbut use the files in the git clone.\n\n```sh\n\u003e git clone --recursive git@github.com:luvit/lit.git\n\u003e cd lit\n\u003e make # If using official luvi binary\n```\n\nIf you're using a custom built luvi binary instead of the official ones, you'll\nneed to manually run the make step with something like:\n\n```sh\n# $CUSTOM_LUVI is the path to your custom luvi binary.\n\u003e $CUSTOM_LUVI . -- make . ./lit $CUSTOM_LUVI\n```\n\nOnce you have lit built, you'll want to install it somewhere in your path. (For\nexample `/usr/local/bin/`.)\n\n```sh\n\u003e sudo install lit /usr/local/bin\n```\n\n## Command-Line Interface\n\nLit is a multi-functionality toolkit, it has many groups of commands via it's\nCLI.\n\n#### `lit help`\n\nThis will print a [high-level cheatsheet](./commands/README) of all the commands\nin the interface to your terminal.\n\n#### `lit version`\n\nThis simple command will print the lit version and exit.  It's useful to verify\nwhich version of lit you have installed from a script.\n\n#### `lit init`\n\nThis will run through a series of questions that will help you scaffold\nout either\na `init.lua` file (used for simple packages) or a `package.lua` file\n(used for more complicated or advanced projects).\n\n### Local Configuration\n\nThese commands are for working with your local lit config file.\n\n#### `lit auth username`\n\nThis command is used to authenticate as a github user.  It assumes you have a\nRSA private key located at `$HOME/.ssh/id_rsa` and downloads your public keys\nfrom github looking for one that matches the private key on the disk.  Once\nverified you are the person you claim to be, this private key will be used to\nsign packages you create to be published.\n\n#### `lit up [url]`\n\nBy default lit is configured to use `wss://lit.luvit.io` as it's upstream\nrepository.  You can set a new custom upstream here.  If you're down (because of\n`lit down`) this will bring you back online.  If the url is ommitted, the\n`defaultUpstream` in your config will be used.\n\nWhen online, lit will check the upstream when looking for package matches and\ndownload and cache any new data on demand.\n\n#### `lit down`\n\nIf your internet connection is slow or unreliable, you can use lit in offline\nmode.  This will skip all calls to the upstream and work as a standalone\ndatabase using your cache.  This works surprisingly well once the packages you\ncommonly use are cached locally.\n\n#### `lit config`\n\nThis simple helper will dump the contents of your config file for easy viewing\n\n### Package Management\n\nLit's primary usage is probably as a package manager and client to the package\nrepository.\n\n#### `lit add path*`\n\nGiven one or more paths to modules (folders or files containing lit metadata),\nlit will read the metadata, import the file or folders into the database and\ncreate a tagged release (signing if you're authenticated).\n\nThese packages can then be later published to an upstream or installed locally\nin some other folder.\n\n#### `lit publish path*`\n\nPublish will first run `lit add path*` to ensure the latest version is imported\ninto the database.  It will then iterate over the local versions and upload any\nthat aren't yet on the upstream.\n\n#### `lit install`\n\nRunning `lit install` in a folder containing lit metadata will install all it's\ndependencies recursivly to the local `deps` folder.  If any of the\ndependencies already exist there, they will be skipped, even if there is a new\nversion in the database.\n\n#### `lit install names*`\n\nYou can also install one or more lit packages directly by name without setting\nup a metadata file.\n\nFor example, this will install the latest version of `creationix/git` to modules\n(even if there is something already there)\n\n```sh\n\u003e lit install creationix/git\n```\n\n#### `lit sync`\n\nIf you like to work offline a lot, it's useful to run `lit sync` when online to\nmake sure the cached packages in your local database have the latest versions\ncached.\n\nHere is an example of going inline, checking for updates and then going back\noffline.\n\n```sh\n\u003e lit up\n\u003e lit sync\n\u003e lit down\n```\n\n### Upstream Organization Management\n\nBy default, you can only publish to upstream prefixes that match your github\nusername, but you can also publish to github organization names if you've set as\nan other of that org in the lit upstream.\n\n#### `lit claim org`\n\nIf you're a public member of an org on github, you can add yourself as an owner\nto the corresponding org in the lit upstream.\n\n#### `lit share org username`\n\nOnce you're an owner, you can add anyone as collaborators and co-owners with the\nshare command.\n\n#### `lit unclaim org`\n\nYou can remove yourself from the list of owners with this command.\n\n### Execution and Packaging\n\nLuvi apps can be run and created using the `luvi` tool directly, but lit\nprovides easier interfaces to this and adds new functionality.\n\n#### `lit make path/to/app [target]`\n\nWhen you're ready to package your luvi app into a single binary, you can use\nlit's make command.  This is more than simply setting `LUVI_TARGET`.  It will\nread the `package.lua` metadata to get the name of the target.  Also it will\ninject any missing dependencies into the bundle embedded in the executable.\n\nAlso the `package.lua` can contain a white-list of black-list of files to\ninclude in the final bundle.  See examples in\n[luvit](https://github.com/luvit/luvit/blob/luvi-up/package.lua) and\n[lit](https://github.com/luvit/lit/blob/master/package.lua).\n\nFor example, lit's own bootstrap uses a combination of `LUVI_APP` and `lit make`\nto build itself with nothing more than the luvi executable and a zip file\ncontaining lit's source.\n\n```sh\n\u003e luvi lit.zip -- make lit.zip\n```\n\nThis will run the app contained in lit.zip passing in the arguments `make` and\n`lit.zip`.  The `make` will trigger lit's make command and it will build a lit\nexecutable from the contents of the zip file, installing any dependencies not\nfound in the zip.\n\n### Lit Server\n\nIt's trivial to setup your own caching proxy or private repository of lit\npackages.  Simply install lit on the server and run `lit serve`.  If you have\nan upstream configured this server will act as a caching proxy.  Any requests\nnot found locally will be fetched from the upstream and cached locally.  Any\npackages published locally will be kept local (private).\n\nIt's highly encouraged to setup such proxies if you have deployments that\ndepend on lit packages.  Never use the public repository directly for\nrepetitive and/or mission critical scripts.\n\nThe server listens on port `4822` by default.\n\n```\n\u003e lit serve\nlit version: 0.9.8\ncommand: serve\nload config: /home/tim/.litconfig\n```\n\n## Lit as a Library\n\nAlso you can use lit as a library via it's core interface.\n\nThis interface is is documented in [The libs README](./libs/README).\n\n## REST API\n\nLit servers export a simple REST based interface for browsing the package contents.\n\nThis is a simple rest API for reading the remote database over HTTP.\nIt uses hypermedia in the JSON responses to make linking between requests simple.\n\nThe API for the main lit repository can be found at https://lit.luvit.io/\n\n```\nGET / -\u003e api json {\n  blobs = \"/blobs/{hash}\"\n  trees = \"/trees/{hash}\"\n  packages = \"/packages{/author}{/tag}{/version}\"\n}\nGET /blobs/$HASH -\u003e raw data\nGET /trees/$HASH -\u003e tree json {\n foo = { mode = 0644, hash = \"...\", url=\"/blobs/...\" }\n bar = { mode = 0755, hash = \"...\", url=\"/trees/...\" }\n ...\n}\nGET /packages -\u003e authors json {\n  creationix = \"/packages/creationix\"\n  ...\n}\nGET /packages/$AUTHOR -\u003e tags json {\n  git = \"/packages/creationix/git\"\n  ...\n}\nGET /packages/$AUTHOR/$TAG -\u003e versions json {\n  v0.1.2 = \"/packages/creationix/git/v0.1.2\"\n  ...\n}\nGET /packages/$AUTHOR/$TAG/$VERSION -\u003e tag json {\n  hash = \"...\"\n  object = \"...\"\n  object_url = \"/trees/...\"\n  type = \"tree\"\n  tag = \"v0.2.3\"\n  tagger = {\n    name = \"Tim Caswell\",\n    email = \"tim@creationix.com\",\n    date = {\n      seconds = 1423760148\n      offset = -0600\n    }\n  }\n  message = \"...\"\n}\n```\n\n## Package Metadata\n\nLit packages need some form of metadata embedded in the lua files.  Packages can\nbe either single lua files or directories containing many files.  If your\nlibrary is a single file, simply set `name` and `version` and optionally\n`dependencies` at the top of your file in a comment block wrapped with\n`--[[lit-meta ... ]]`.  It will then be able to be imported into lit and\npublished to the repository.\n\nFor more complex packages, lit will search first in `package.lua` and then in\n`init.lua`. The first file found will need to export or return a table\ncontaining the `name`, `version` and `dependencies` metadata.\n\nHere is an example of a single-file package\n\n```lua\n-- bad-math.lua\n-- Dead simple library\n--[[lit-meta\n  name = \"creationix/bad-math\"\n  version = \"0.0.1\"\n]]\n\nfunction add(a, b)\n  return a - b\nend\n\nreturn { add = add }\n```\n\nThis can then be published with `lit publish bad-math.lua`, it can be installed\nwith `lit install creationix/bad-math.lua` and dependend on with a\n`dependencies` entry of `creationix/bad-math@0.0.1`.\n\nIf this was in a larger package, it could have a package.lua containing:\n\n```lua\n-- bad-math/package.lua\nreturn {\n  name = \"creationix/bad-math\",\n  version = \"0.0.1\",\n}\n```\n\nThis could be published with `lit publish bad-math`.\n\n## Internals\n\nLit is written in lua and uses the same system platform as the luvit project,\nbut is has a very different I/O style.  Instead of using callbacks and event\nemitters, it uses coroutines so that code can be written with simple blocking\nI/O, but still maintain the abilities of a non-blocking event loop.\n\nLit internally uses a git compatable database on disk for storing packages and\nrelease tags.  The releases are actual git tags at\n`refs/tags/$username/$name/v$version`.  These point to annotated tags that\ncontain an RSA signature (signed by the user's SSH private key as used on\ngithub).  These tags then point directly to either trees or blobs.  Git commits\nare never used in this system.\n\nThe network protocol is based on websockets.  The entire protocol is safe to use\nin the open and doesn't require TLS for security since everything is verified\nusing SHA1 git hashes and signed and verified using RSA.  However, the client\nand the central repository do support communication over TLS for clients on\nnetworks containing HTTP proxies that break normal communication.\n\nIf you experience troubles on your company network, try setting your `upstream`\nand `defaultUpstream` in your `.litconfig` to `wss://lit.luvit.io/`.  The cert\nis invalid, but that doesn't matter here since we're simply trying to confuse\nthe proxy and not gain security from the socket.\n\nBoth the server and client query github using a REST API to get the public keys\nof users when verifying signatures in package tags.  These keys are cached\nlocally inside the git database under `keys/$username/$fingerprint`.  Also\norganization membership is stored under keys at `keys/$orgname.owners` in a\nnewline delimited file of usernames.\n\nFor full details read the source.  The libs folder has a nice [internal\nREADME](./libs/README) to get you started.\n\n[luvit]: https://github.com/luvit/luvit/\n[luvi]:https://github.com/luvit/luvi/\n\n## Development\n\nWhen working on Lit, `luvi` can be used to run `lit` from source without building by using the command at the root of the `lit` source directory:\n\n```\nluvi .\n```\nor\n```\nluvi . -- args\n```\n\nFor example, if you were working on something to do with the `lit serve` command, your changes could be tested with:\n\n```\nluvi . -- serve\n```\n\n## Running Tests\n\nTests for the Lit libraries can be run via luvi:\n\n```\nluvi tests -- tests/run.lua\n```\n\nor to run a specific test file (in this case the `coro-http` tests):\n\n```\nluvi tests -- tests/test-coro-http.lua\n```\n","funding_links":[],"categories":["Lua","package-manager"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluvit%2Flit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluvit%2Flit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluvit%2Flit/lists"}