fix(pack): consistently use "revision" instead of "state"

Problem: In some areas plugin's revision is named "state". This might be
  confusing for the users.

Solution: Consistently use "revision" to indicate "plugin's state on
  disk".

runtime/doc/pack.txt

@@ -273,7 +273,7 @@ Basic install and management:
 Switch plugin's version:
 • Update 'init.lua' for plugin to have desired `version`. Let's say, plugin
   named 'plugin1' has changed to `vim.version.range('*')`.
-• |:restart|. The plugin's actual state on disk is not yet changed. Only
+• |:restart|. The plugin's actual revision on disk is not yet changed. Only
   plugin's `version` in |vim.pack-lockfile| is updated.
 • Execute `vim.pack.update({ 'plugin1' })`.
 • Review changes and either confirm or discard them. If discarded, revert any
@@ -356,7 +356,7 @@ add({specs}, {opts})                                          *vim.pack.add()*
       |vim.pack-directory|:
       • If exists, do nothing in this step.
       • If doesn't exist, install it by downloading from `src` into `name`
-        subdirectory (via `git clone`) and update state to match `version`
+        subdirectory (via `git clone`) and update revision to follow `version`
         (via `git checkout`).
     • For each plugin execute |:packadd| (or customizable `load` function)
       making it reachable by Nvim.
@@ -365,7 +365,7 @@ add({specs}, {opts})                                          *vim.pack.add()*
     • Installation is done in parallel, but waits for all to finish before
       continuing next code execution.
     • If plugin is already present on disk, there are no checks about its
-      present state. The specified `version` can be not the one actually
+      current revision. The specified `version` can be not the one actually
       present on disk. Execute |vim.pack.update()| to synchronize.
     • Adding plugin second and more times during single session does nothing:
       only the data from the first adding is registered.
@@ -416,7 +416,7 @@ get({names}, {opts})                                          *vim.pack.get()*
 update({names}, {opts})                                    *vim.pack.update()*
     Update plugins
     • Download new changes from source.
-    • Infer update info (current/target state, changelog, etc.).
+    • Infer update info (current/target revisions, changelog, etc.).
     • Depending on `force`:
       • If `false`, show confirmation buffer. It lists data about all set to
         update plugins. Pending changes starting with `>` will be applied

runtime/ftplugin/nvim-pack.lua

@@ -18,7 +18,7 @@ local cur_header_hl_group = nil
 local lines = vim.api.nvim_buf_get_lines(0, 0, -1, false)
 for i, l in ipairs(lines) do
   local cur_group = l:match('^# (%S+)')
-  local cur_info = l:match('^Path: +') or l:match('^Source: +') or l:match('^State[^:]*: +')
+  local cur_info = l:match('^Path: +') or l:match('^Source: +') or l:match('^Revision[^:]*: +')
   if cur_group ~= nil then
     --- @cast cur_group string
     -- Header 1
@@ -32,7 +32,7 @@ for i, l in ipairs(lines) do
     local end_col = l:match('(). +%b()$') or l:len()
     hi_range(i, cur_info:len(), end_col, 'DiagnosticInfo')
 
-    -- Plugin state after update
+    -- Plugin version after update
     local col = l:match('() %b()$')
     if col then
       hi_range(i, col, l:len(), 'DiagnosticHint')

runtime/lua/vim/pack.lua

@@ -70,7 +70,7 @@
 ---Switch plugin's version:
 ---- Update 'init.lua' for plugin to have desired `version`. Let's say, plugin
 ---named 'plugin1' has changed to `vim.version.range('*')`.
----- |:restart|. The plugin's actual state on disk is not yet changed.
+---- |:restart|. The plugin's actual revision on disk is not yet changed.
 ---  Only plugin's `version` in |vim.pack-lockfile| is updated.
 ---- Execute `vim.pack.update({ 'plugin1' })`.
 ---- Review changes and either confirm or discard them. If discarded, revert
@@ -602,7 +602,7 @@ end
 
 --- @async
 --- @param p vim.pack.Plug
-local function infer_states(p)
+local function infer_revisions(p)
   p.info.sha_head = p.info.sha_head or git_get_hash('HEAD', p.path)
 
   resolve_version(p)
@@ -616,7 +616,7 @@ end
 --- @param p vim.pack.Plug
 --- @param timestamp string
 local function checkout(p, timestamp)
-  infer_states(p)
+  infer_revisions(p)
 
   local msg = ('vim.pack: %s Stash before checkout'):format(timestamp)
   git_cmd({ 'stash', '--quiet', '--message', msg }, p.path)
@@ -668,7 +668,7 @@ end
 --- @param p vim.pack.Plug
 local function infer_update_details(p)
   p.info.update_details = ''
-  infer_states(p)
+  infer_revisions(p)
   local sha_head = assert(p.info.sha_head)
   local sha_target = assert(p.info.sha_target)
 
@@ -756,14 +756,14 @@ end
 --- - For each specification check that plugin exists on disk in |vim.pack-directory|:
 ---     - If exists, do nothing in this step.
 ---     - If doesn't exist, install it by downloading from `src` into `name`
----       subdirectory (via `git clone`) and update state to match `version` (via `git checkout`).
+---       subdirectory (via `git clone`) and update revision to follow `version` (via `git checkout`).
 --- - For each plugin execute |:packadd| (or customizable `load` function) making
 ---   it reachable by Nvim.
 ---
 --- Notes:
 --- - Installation is done in parallel, but waits for all to finish before
 ---   continuing next code execution.
---- - If plugin is already present on disk, there are no checks about its present state.
+--- - If plugin is already present on disk, there are no checks about its current revision.
 ---   The specified `version` can be not the one actually present on disk.
 ---   Execute |vim.pack.update()| to synchronize.
 --- - Adding plugin second and more times during single session does nothing:
@@ -852,7 +852,7 @@ local function compute_feedback_lines_single(p)
     parts[#parts + 1] = table.concat({
       'Path:     ' .. p.path,
       'Source:   ' .. p.spec.src,
-      'State:  ' .. p.info.sha_target .. version_suffix,
+      'Revision: ' .. p.info.sha_target .. version_suffix,
     }, '\n')
 
     if p.info.update_details ~= '' then
@@ -863,8 +863,8 @@ local function compute_feedback_lines_single(p)
     parts[#parts + 1] = table.concat({
       'Path:            ' .. p.path,
       'Source:          ' .. p.spec.src,
-      'State before: ' .. p.info.sha_head,
+      'Revision before: ' .. p.info.sha_head,
-      'State after:  ' .. p.info.sha_target .. version_suffix,
+      'Revision after:  ' .. p.info.sha_target .. version_suffix,
       '',
       'Pending updates:',
       p.info.update_details,
@@ -996,7 +996,7 @@ end
 --- Update plugins
 ---
 --- - Download new changes from source.
---- - Infer update info (current/target state, changelog, etc.).
+--- - Infer update info (current/target revisions, changelog, etc.).
 --- - Depending on `force`:
 ---     - If `false`, show confirmation buffer. It lists data about all set to
 ---       update plugins. Pending changes starting with `>` will be applied while

runtime/lua/vim/pack/_lsp.lua

@@ -194,7 +194,7 @@ methods['textDocument/hover'] = function(params, callback)
 
   local lines = vim.api.nvim_buf_get_lines(bufnr, 0, -1, false)
   local lnum = params.position.line + 1
-  local commit = lines[lnum]:match('^[<>] (%x+) │') or lines[lnum]:match('^State.*:%s+(%x+)')
+  local commit = lines[lnum]:match('^[<>] (%x+) │') or lines[lnum]:match('^Revision.*:%s+(%x+)')
   local tag = lines[lnum]:match('^• (.+)$')
   if commit == nil and tag == nil then
     return

test/functional/plugin/pack_spec.lua

@@ -1057,8 +1057,8 @@ describe('vim.pack', function()
           '{101:## fetch}                                                                             |',
           'Path:            {103:FETCH_PATH}                                                          |',
           'Source:          {103:FETCH_SRC}                                                           |',
-          ('State before: {103:%s}                               |'):format(hashes.fetch_head),
+          ('Revision before: {103:%s}                            |'):format(hashes.fetch_head),
-          ('State after:  {103:%s} {102:(main)}                        |'):format(hashes.fetch_new),
+          ('Revision after:  {103:%s} {102:(main)}                     |'):format(hashes.fetch_new),
           '                                                                                     |',
           'Pending updates:                                                                     |',
           ('{19:< %s │ Commit from `main` to be removed}                                         |'):format(
@@ -1076,7 +1076,7 @@ describe('vim.pack', function()
           '{102:## semver}                                                                            |',
           'Path:     {103:SEMVER_PATH}                                                                |',
           'Source:   {103:SEMVER_SRC}                                                                 |',
-          ('State:  {103:%s} {102:(v0.3.0)}                            |'):format(
+          ('Revision: {103:%s} {102:(v0.3.0)}                          |'):format(
             hashes.semver_head
           ),
           '                                                                                     |',
@@ -1121,8 +1121,8 @@ describe('vim.pack', function()
           ## fetch
           Path:            %s
           Source:          %s
-          State before: %s
+          Revision before: %s
-          State after:  %s (main)
+          Revision after:  %s (main)
 
           Pending updates:
           < %s │ Commit from `main` to be removed
@@ -1472,8 +1472,8 @@ describe('vim.pack', function()
         ## fetch
         Path:            %s
         Source:          %s
-        State before: %s
+        Revision before: %s
-        State after:  %s (main)
+        Revision after:  %s (main)
 
         Pending updates:
         < %s │ Commit from `main` to be removed