dotfiles: install the common tools every project on these machines expects

[dotfiles] / README.md

diff --git a/README.md b/README.md
index 063056a142c969531ac610b8bad1eea65caee9c6..dfe024e6efa0f2594889dcfe22b7e2875302e414 100644 (file)
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ throwaway VM reachable from a Linux host.
 
 | File | Purpose |
 | --- | --- |
 
 | File | Purpose |
 | --- | --- |

-| `setup-windows.bat` | Entry point. Runs the winget installs, then the non-elevated script, then launches the elevated half and prints its log. |
+| `setup-windows.bat` | Entry point. Runs the winget installs, then launches the elevated half and prints its log, then runs the non-elevated script. |

 | `setup-windows-no-uac.ps1` | The non-elevated, per-user half: WinMerge and BinSkim on the user `PATH`, and the global git config (identity, plus `core.sshCommand`). Can also be run directly from an ordinary prompt. |
 | `setup-windows-with-uac.ps1` | The elevated half, started via UAC by the batch file. Enables `ssh-agent`, installs the OpenSSH Client and Server capabilities and starts `sshd`, unpacks the `rsync-windows` release zip for this architecture (`rsync.exe` plus the `ssh.exe` it runs) into `C:\Tools\rsync` on the machine `PATH`, then installs Visual Studio 2022 Community with the required components, the WDK, and the Windows Performance Toolkit. Can also be run directly from an Administrator prompt. |
 
 | `setup-windows-no-uac.ps1` | The non-elevated, per-user half: WinMerge and BinSkim on the user `PATH`, and the global git config (identity, plus `core.sshCommand`). Can also be run directly from an ordinary prompt. |
 | `setup-windows-with-uac.ps1` | The elevated half, started via UAC by the batch file. Enables `ssh-agent`, installs the OpenSSH Client and Server capabilities and starts `sshd`, unpacks the `rsync-windows` release zip for this architecture (`rsync.exe` plus the `ssh.exe` it runs) into `C:\Tools\rsync` on the machine `PATH`, then installs Visual Studio 2022 Community with the required components, the WDK, and the Windows Performance Toolkit. Can also be run directly from an Administrator prompt. |
 


@@ -50,15 +50,27 @@ throwaway VM reachable from a Linux host.
 - The elevated half writes a transcript to `setup-windows-uac.log` next to the
   script; the batch file prints it when the elevated window closes. The log is
   gitignored, as it contains local paths.
 - The elevated half writes a transcript to `setup-windows-uac.log` next to the
   script; the batch file prints it when the elevated window closes. The log is
   gitignored, as it contains local paths.

-- **git uses the Windows SSH client.** `setup-windows-no-uac.ps1` sets
-  `core.sshCommand` to `%WINDIR%/System32/OpenSSH/ssh.exe`. Git for Windows
-  otherwise prefers its own bundled MSYS2 `ssh.exe`, which cannot reach the
-  Windows `ssh-agent` service that the elevated half enables - Win32-OpenSSH
-  publishes the agent on a named pipe the MSYS2 build does not speak. Without
-  this, keys loaded with `ssh-add` from PowerShell are invisible to `git`, and a
-  push falls back to hunting for a key file and prompting for its passphrase.
-  The value uses forward slashes on purpose: git parses `core.sshCommand` with
-  shell quoting rules, in which a backslash is an escape character.
+- **git uses a Win32-OpenSSH client.** `setup-windows-no-uac.ps1` sets
+  `core.sshCommand`. Git for Windows otherwise prefers its own bundled MSYS2
+  `ssh.exe`, which cannot reach the Windows `ssh-agent` service that the elevated
+  half enables - Win32-OpenSSH publishes the agent on a named pipe the MSYS2
+  build does not speak. Without this, keys loaded with `ssh-add` from PowerShell
+  are invisible to `git`, and a push falls back to hunting for a key file and
+  prompting for its passphrase. The value uses forward slashes on purpose: git
+  parses `core.sshCommand` with shell quoting rules, in which a backslash is an
+  escape character.
+- **Which `ssh.exe` git gets.** `C:\Tools\rsync\ssh.exe` — the fast build the
+  elevated half unpacks — if it is there, `%WINDIR%/System32/OpenSSH/ssh.exe`
+  otherwise. It is the same client with the same `~/.ssh`, agent and
+  `known_hosts`; the difference is the stdin pump, and without it anything git
+  *pushes* is capped at ~17 MB/s. Candidates are tried by **running** them
+  (`ssh -V`), not by `Test-Path`: the fast build needs a `libcrypto.dll` that an
+  image without the OpenSSH Client capability does not have, and a client that
+  will not start should be found here rather than on the next `git push`.
+  This is also why `setup-windows.bat` now runs the elevated half **first** — the
+  fast `ssh.exe` has to exist before the git config step can prefer it. The
+  non-elevated half still runs even when the elevated one failed; it just falls
+  back. Re-run `setup-windows-no-uac.ps1` on its own at any time to re-pick.

 - All three scripts are idempotent — re-running skips anything already installed.
   BinSkim in particular checks NuGet for the newest stable version *before*
   downloading: the package is a self-contained .NET build well over 100 MB, and
 - All three scripts are idempotent — re-running skips anything already installed.
   BinSkim in particular checks NuGet for the newest stable version *before*
   downloading: the package is a self-contained .NET build well over 100 MB, and