*arti-pack.txt*   Install Neovim plugins from an artifact store

==============================================================================
CONTENTS                                                   *arti-pack-contents*

  1. Introduction ......................... |arti-pack-introduction|
  2. Setup ................................ |arti-pack-setup|
  3. Plugin specs ......................... |arti-pack-specs|
  4. Commands ............................. |arti-pack-commands|
  5. Layout ............................... |arti-pack-layout|

==============================================================================
1. INTRODUCTION                                        *arti-pack-introduction*

arti-pack installs plugins from tagged upstream source archives served over
HTTP by an artifact repository, and unpacks them into Neovim's native package
path. See |packages| for how Neovim loads what arti-pack writes.

Any artifact repository that serves an upstream tag archive at a stable URL
works — a JFrog Artifactory remote GitHub repository, or any caching proxy
with the same path shape. Nothing is cloned and the editor never reaches
GitHub itself.

Requires curl. Zip and tar.gz archives are unpacked in pure Lua, so no
unzip or tar binary is needed. Entry paths are validated and every
entry's CRC32 is checked before it lands on disk.

==============================================================================
2. SETUP                                                      *arti-pack-setup*

                                                            *arti-pack.setup()*
>lua
    require('arti-pack').setup({
      registry = 'https://artifacts.example.com/artifactory/github-remote',
      plugins = {
        { 'nvim-lua/plenary.nvim', tag = 'v0.1.4' },
        { 'folke/which-key.nvim', tag = 'v3.13.3', opt = true },
      },
    })
<
Options:

  registry     Required, no default. Archive URL prefix placed in front of
               "owner/repo", pointing at your own artifact repository. It
               must be an http:// or https:// URL; surrounding whitespace
               is trimmed and anything else is rejected at setup, so a
               stray space never reaches the download. Until it is set,
               |:ArtiPackSync| refuses to run and says which option to
               set. |:ArtiPackClean| and |:ArtiPackList| never resolve a
               URL and work without it, as do plugin specs carrying an
               explicit "url".
  plugins      List of plugin specs. See |arti-pack-specs|.
  auto_sync    Sync missing and changed plugins on startup. Default true.
  concurrency  Plugins downloaded in parallel. Default 4.
  timeout      Per-download timeout in seconds. Default 120.

==============================================================================
3. PLUGIN SPECS                                               *arti-pack-specs*

Each entry is a table whose first element is "owner/repo".

  tag    Required. Upstream tag, used verbatim in the archive path.
  opt    Install under opt/ for |:packadd| instead of start/. Default false.
  as     Directory name to install as. Defaults to the repo name.
  ext    "zip" or "tar.gz". Default "zip".
  url    Full archive URL, bypassing the registry. Trimmed; it may not
         contain whitespace.

The archive URL is built as: >
    <registry>/<owner>/<repo>/archive/refs/tags/<tag>.<ext>
<
==============================================================================
4. COMMANDS                                                *arti-pack-commands*

                                                                *:ArtiPackSync*
:ArtiPackSync     Install missing plugins and update ones whose tag changed.
:ArtiPackSync!    Reinstall every configured plugin, ignoring recorded state.

                                                               *:ArtiPackClean*
:ArtiPackClean    Remove installed plugins that are no longer in the spec.

                                                                *:ArtiPackList*
:ArtiPackList     Show every configured plugin and its state.

==============================================================================
5. LAYOUT                                                    *arti-pack-layout*

  stdpath('data')/site/pack/arti-pack/start/<name>   loaded at startup
  stdpath('data')/site/pack/arti-pack/opt/<name>     loaded by |:packadd|
  stdpath('data')/arti-pack/lock.json                recorded tags
  stdpath('cache')/arti-pack                         downloaded archives

Downloads are checked for a zip or gzip magic header before being trusted, and
the single "<repo>-<version>" directory that tag archives wrap their contents
in is stripped on the way in. A plugin that fails is reported and skipped; the
rest of the run continues.

vim:tw=78:ts=8:noet:ft=help:norl:
