docs(lockfile): Upgrade moved to optional args

EdenEast · EdenEast · commit 64127198f552 · 2022-10-04T10:33:38.000-04:00
diff --git a/README.md b/README.md
@@ -178,34 +178,23 @@ end)
 
 `packer` provides the following commands after you've run and configured `packer` with `require('packer').startup(...)`:
 
-```
--- You must run this or `PackerSync` whenever you make changes to your plugin configuration
--- Regenerate compiled loader file
-:PackerCompile
-
--- Remove any disabled or unused plugins
-:PackerClean
-
--- Clean, then install missing plugins
-:PackerInstall
-
--- Clean, then update and install plugins
--- supports the `--preview` flag as an optional first argument to preview updates
-:PackerUpdate
-
--- Perform `PackerUpdate` and then `PackerCompile`
--- supports the `--preview` flag as an optional first argument to preview updates
-:PackerSync
-
--- Perform `PackerUpdate` without lockfile.
-:PackerUpgrade
-
--- Loads opt plugin immediately
-:PackerLoad completion-nvim ale
-
--- Updates lockfile from installed plugins.
-:PackerLockfile
-```
+- `:PackerCompile` Regenerate compiled loader file
+  - You must run this or `PackerSync` whenever you make changes to your plugin configuration
+- `:PackerClean` Remove any disabled or unused plugins
+- `:PackerInstall` Clean, then install missing plugins. Supports optional arguments
+  - `--nolockfile`: Do not apply lockfile if enabled
+  - `--lockfile=/path/lockfile.lua`: Override lockfile used
+- `:PackerUpdate` Clean, then update and install plugins. Supports optional arguments
+  - `--preview`: Preview updates before applying
+  - `--nolockfile`: Do not apply lockfile if enabled
+  - `--lockfile=/path/lockfile.lua`: Override lockfile used
+- `:PackerSync` Perform `PackerUpdate` and then `PackerCompile`. Supports optional arguments
+  - `--preview`: Preview updates before applying
+  - `--nolockfile`: Do not apply lockfile if enabled
+  - `--lockfile=/path/lockfile.lua`: Override lockfile used
+- `:PackerLoad` Loads opt plugin immediately
+- `:PackerLockfile` Updates lockfile from installed plugins. Supports optional arguments
+  - `--path=/path/lockfile.lua`: Override lockfile output
 
 You can configure Neovim to automatically run `:PackerCompile` whenever `plugins.lua` is updated with
 [an autocommand](https://neovim.io/doc/user/autocmd.html#:autocmd):
@@ -363,7 +352,7 @@ default configuration values (and structure of the configuration table) are:
   lockfile = {
     enable = false, -- Should packer apply lockfile to `installer` and `updater`
     path = util.join_paths(stdpath 'config', 'lockfile.lua'), -- Default file location for lockfile
-    update_on_upgrade = false, -- Should packer update the lockfile after upgrading plugins
+    regen_on_update = false, -- Should packer update the lockfile after upgrading plugins
   },
   luarocks = {
     python_cmd = 'python' -- Set the python command to use for running hererocks
@@ -421,11 +410,12 @@ use {
   ft = string or list,         -- Specifies filetypes which load this plugin.
   keys = string or list,       -- Specifies maps which load this plugin. See "Keybindings".
   event = string or list,      -- Specifies autocommand events which load this plugin.
-  fn = string or list          -- Specifies functions which load this plugin.
+  fn = string or list,         -- Specifies functions which load this plugin.
   cond = string, function, or list of strings/functions,   -- Specifies a conditional test to load this plugin
-  module = string or list      -- Specifies Lua module names for require. When requiring a string which starts
+  module = string or list,     -- Specifies Lua module names for require. When requiring a string which starts
                                -- with one of these module names, the plugin will be loaded.
-  module_pattern = string/list -- Specifies Lua pattern of Lua module names for require. When requiring a string which matches one of these patterns, the plugin will be loaded.
+  module_pattern = string/list -- Specifies Lua pattern of Lua module names for require. When requiring a
+                              -- string which matches one of these patterns, the plugin will be loaded.
 }
 ```
 
@@ -544,14 +534,20 @@ below, `plugins` is an optional table of plugin names; if not provided, the defa
 plugins":
 
 - `packer.install(plugins)`: Install the specified plugins if they are not already installed
+- `packer.install(opts, plugins)`: First argument can be a table of optional args
+  - `nolockfile`: `boolean` Should the command use the lockfile
+  - `lockfile`: `string` Override the default lockfile path to be used
 - `packer.update(plugins)`: Update the specified plugins, installing any that are missing
-- `packer.update(opts, plugins)`: First argument can be a table specifying options, such as `{preview_updates = true}` to preview potential changes before updating (same as `PackerUpdate --preview`).
+- `packer.update(opts, plugins)`: First argument can be a table specifying options
+  - `preview`: `boolean` Preview potential change before updating
+  - `nolockfile`: `boolean` Should the command use the lockfile
+  - `lockfile`: `string` Override the default lockfile path to be used
 - `packer.clean()`: Remove any disabled or no longer managed plugins
 - `packer.sync(plugins)`: Perform a `clean` followed by an `update`.
 - `packer.sync(opts, plugins)`: Can take same optional options as `update`.
-- `packer.upgrade(plugins)`: Performs an `update` without applying the lockfile
 - `packer.compile(path)`: Compile lazy-loader code and save to `path`.
-- `packer.lockfile()`: Updates lockfile based on currently installed plugins
+- `packer.lockfile(opts)`: Updates lockfile based on currently installed plugins
+  - `path`: `string` Override lockfile output path
 - `packer.snapshot(snapshot_name, ...)`: Creates a snapshot file that will live under `config.snapshot_path/<snapshot_name>`. If `snapshot_name` is an absolute path, then that will be the location where the snapshot will be taken. Optionally, a list of plugins name can be provided to selectively choose the plugins to snapshot.
 - `packer.rollback(snapshot_name, ...)`: Rollback plugins status a snapshot file that will live under `config.snapshot_path/<snapshot_name>`. If `snapshot_name` is an absolute path, then that will be the location where the snapshot will be taken. Optionally, a list of plugins name can be provided to selectively choose which plugins to revert.
 - `packer.delete(snapshot_name)`: Deletes a snapshot file under `config.snapshot_path/<snapshot_name>`. If `snapshot_name` is an absolute path, then that will be the location where the snapshot will be deleted.
@@ -592,6 +588,40 @@ name and information table as arguments.
 configuration in some sort of source repository. Committing packer's lockfile will ensure that packer will
 `install` and `update` plugins to known working commits for their configuration.
 
+Enabling lockfile support will change the default behavior of `install`, `update`, and `sync` commands.
+If the lockfile contains a plugin, packer will update to that commit instead of the latest changes. If the
+plugin is not found in the lockfile packer will fetch the latest changes.
+
+When wanting to update your local plugins to the latest changes call your packer update command with
+`--nolockfile` argument. This will ignore the lockfile and update your plugins to the latest changes.
+
+Some example commands:
+
+```vim
+" Generate the lockfile to lockfile.path defined in packer's config
+PackerLockfile
+
+" Generating a lockfile to some other path
+PackerLockfile --path="/some/other/path.lua"
+
+" Update plugins to the state defined in lockfile
+PackerUpdate
+
+" Updating without applying lockfile
+PackerUpdate --nolockfile
+
+" Updating a specific plugin without applying lockfile
+PackerUpdate --nolockfile plenary.nvim
+
+" Updating plugins and applying a specific lockfile
+PackerUpdate --lockfile="/some/other/path.lua"
+
+" Updating a specific plugin with a specific lockfile
+PackerUpdate --lockfile="/some/other/path.lua" plenary.nvim
+```
+
+The same options that apply to `PackerUpdate` also apply to `PackerInstall` and `PackerSync`.
+
 ### User autocommands
 `packer` runs most of its operations asyncronously. If you would like to implement automations that
 require knowing when the operations are complete, you can use the following `User` autocmds (see
diff --git a/doc/packer.txt b/doc/packer.txt
@@ -118,33 +118,39 @@ configuration. Regenerate compiled loader file.
 
 `PackerInstall`                                 *packer-commands-install*
 Clean, then install missing plugins.
+Optional arguments:
+    `--nolockfile`                  Do not apply lockfile if enabled
+    `--lockfile=/path/lockfile.lua` Override lockfile used
 
 `PackerUpdate`                                  *packer-commands-update*
 Clean, then update and install plugins.
-Supports the `--preview` flag as an optional first argument to preview
-updates.
+Optional arguments:
+    `--preview`                     Preview updates
+    `--nolockfile`                  Do not apply lockfile if enabled
+    `--lockfile=/path/lockfile.lua` Override lockfile used
 
 `PackerSync`                                    *packer-commands-sync*
 Perform `PackerUpdate` and then `PackerCompile`.
-Supports the `--preview` flag as an optional first argument to preview
-updates.
-
-`PackerUpdate`                                  *packer-commands-upgrade*
-Perform `PackerUpdate` without lockfile.
+Optional arguments:
+    `--preview`                     Preview updates
+    `--nolockfile`                  Do not apply lockfile if enabled
+    `--lockfile=/path/lockfile.lua` Override lockfile used
 
 `PackerLockfile`                                *packer-commands-lockfile*
 Updates lockfile from installed plugins.
+Optional arguments:
+    `--path=/path/lockfile.lua`     Override lockfile output
 
 `PackerLoad`                                    *packer-commands-load*
 Loads opt plugin immediately
 
-`PackerSnapshot`                                    *packer-commands-snapshot*
+`PackerSnapshot`                                *packer-commands-snapshot*
 Snapshots your plugins to a file
 
-`PackerSnapshotDelete`                                    *packer-commands-delete*
+`PackerSnapshotDelete`                          *packer-commands-delete*
 Deletes a snapshot
 
-`PackerSnapshotRollback`                                    *packer-commands-rollback*
+`PackerSnapshotRollback`                        *packer-commands-rollback*
 Rolls back plugins' commit specified by the snapshot
 ==============================================================================
 USAGE                                          *packer-usage*
@@ -197,10 +203,9 @@ commands work well for this purpose: >
   command! -nargs=* -complete=customlist,v:lua.require'packer'.plugin_complete  PackerInstall lua require('packer').install(<f-args>)
   command! -nargs=* -complete=customlist,v:lua.require'packer'.plugin_complete PackerUpdate lua require('packer').update(<f-args>)
   command! -nargs=* -complete=customlist,v:lua.require'packer'.plugin_complete PackerSync lua require('packer').sync(<f-args>)
-  command! -nargs=* -complete=customlist,v:lua.require'packer'.plugin_complete PackerUpgrade lua require('packer').upgrade(<f-args>)
+  command! -nargs=* -complete=customlist,v:lua.require'packer.lockfile'.completion PackerLockfile lua require('packer').lockfile(<f-args>)
   command! PackerClean packadd packer.nvim | lua require('plugins').clean()
   command! PackerCompile packadd packer.nvim | lua require('plugins').compile('~/.config/nvim/plugin/packer_load.vim')
-  command! PackerLockfile packadd packer.nvim | lua require('packer').lockfile()
   command! -bang -nargs=+ -complete=customlist,v:lua.require'packer'.loader_complete PackerLoad lua require('packer').loader(<f-args>, '<bang>')
 
 CONFIGURATION                                  *packer-configuration*
@@ -505,10 +510,43 @@ They can be configured by changing the value of `config.display.keybindings`
 Setting any of its keys to `false` will disable the corresponding keybinding.
 
 LOCKFILE                                       *packer-lockfile*
-`packer` provides a `lockfile` to help manage plugin updates. This is useful
-for users that store their configuration in some sort of source repository.
-Committing packer's lockfile will ensure that packer will `install` and
-`update` plugins to known working commits for their configuration.
+`packer` provides a `lockfile` to help manage plugin updates. This is useful for users that store their
+configuration in some sort of source repository. Committing packer's lockfile will ensure that packer will
+`install` and `update` plugins to known working commits for their configuration.
+
+Enabling lockfile support will change the default behavior of `install`, `update`, and `sync` commands.
+If the lockfile contains a plugin, packer will update to that commit instead of the latest changes. If the
+plugin is not found in the lockfile packer will fetch the latest changes.
+
+When wanting to update your local plugins to the latest changes call your packer update command with
+`--nolockfile` argument. This will ignore the lockfile and update your plugins to the latest changes.
+
+Some example commands:
+
+>
+    " Generate the lockfile to lockfile.path defined in packer's config
+    PackerLockfile
+
+    " Generating a lockfile to some other path
+    PackerLockfile --path="/some/other/path.lua"
+
+    " Update plugins to the state defined in lockfile
+    PackerUpdate
+
+    " Updating without applying lockfile
+    PackerUpdate --nolockfile
+
+    " Updating a specific plugin without applying lockfile
+    PackerUpdate --nolockfile plenary.nvim
+
+    " Updating plugins and applying a specific lockfile
+    PackerUpdate --lockfile="/some/other/path.lua"
+
+    " Updating a specific plugin with a specific lockfile
+    PackerUpdate --lockfile="/some/other/path.lua" plenary.nvim
+<
+
+The same options that apply to `PackerUpdate` also apply to `PackerInstall` and `PackerSync`.
 
 USER AUTOCMDS                                  *packer-user-autocmds*
 `packer` runs most of its operations asyncronously. If you would like to
@@ -583,10 +621,6 @@ Additionally, the first argument can be a table specifying options,
 such as `update({preview_updates = true}, ...)` to preview potential changes before updating
 (same as `PackerUpdate --preview`).
 
-upgrade()		                                   *packer.upgrade()*
-`upgrade` performes an `update` without applying the `lockfile`. This will
-update plugins to their latest versions.
-
 snapshot(snapshot_name, ...)		                                *packer.snapshot()*
 `snapshot` takes the rev of all the installed plugins and serializes them into a Lua table which will be saved under `config.snapshot_path` (which is the directory that will hold all the snapshots files) as `config.snapshot_path/<snapshot_name>` or an absolute path provided by the users.
 Optionally plugins name can be specified so that only those plugins will be
