deploy: 8466f0a

Author: bresilla

print.html

@@ -192,6 +192,62 @@ <h1 id="introduction"><a class="header" href="#introduction">Introduction</a></h
 wing project discover ~/code --depth 2
 wing project import ~/code --dry-run
 </code></pre>
+<h2 id="where-a-project-lives"><a class="header" href="#where-a-project-lives">Where a project lives</a></h2>
+<p>A project is registered with the machine it is on. Nothing changes for projects on this machine —
+they simply have no host — but once a project is somewhere else, every question about it has two
+halves, and the registry answers both.</p>
+<pre><code class="language-sh">wing project add api --path /srv/api --machine lab
+wing project set api --machine local        # move it back to this machine
+wing project list                           # the Host column
+wing project list --machine lab             # only what is on lab
+wing project list --local
+wing hosts                                  # which machines have projects, and how many
+</code></pre>
+<pre><code> Host   Projects  Languages
+ local  9         nim, go, rust, zig
+ lab    8         go, d, zig, v, rust, cpp, nim
+ build  0
+</code></pre>
+<p>A machine with no projects still gets a row: "nothing here yet" and "no such machine" are different
+answers, and only one of them means you have not run discovery.</p>
+<h3 id="names-are-qualified-by-host"><a class="header" href="#names-are-qualified-by-host">Names are qualified by host</a></h3>
+<p>The same name on two machines is two projects — a <code>deploy</code> on the build server and a <code>deploy</code> here
+are not the same thing, and on a laptop that talks to five servers there will be several such pairs.
+So a project is addressed as <code>name</code>, or as <code>host:name</code> when the bare name is ambiguous:</p>
+<pre><code>$ wing where api
+'api' is on 2 machines: lab:api, local:api — name one of those instead
+</code></pre>
+<p>Both halves of that answer can be typed straight back in. <code>local:</code> names this machine.</p>
+<h2 id="finding-the-projects-on-a-machine"><a class="header" href="#finding-the-projects-on-a-machine">Finding the projects on a machine</a></h2>
+<pre><code class="language-sh">wing project discover ~/code --machine lab --depth 3        # look
+wing project discover ~/code --machine lab --register       # and keep
+wing project discover ~/code --all-machines --register
+wing project discover ~/code --register                     # this machine
+</code></pre>
+<p>One <code>find</code> per machine, run over ssh, all machines at once — a round trip per candidate directory
+would take minutes. It looks for the markers that mean "a project is here" (<code>.git</code>, <code>Cargo.toml</code>,
+<code>go.mod</code>, <code>*.nimble</code>, <code>pyproject.toml</code>, <code>v.mod</code>, <code>*.cabal</code>, <code>.make.lua</code> and the rest) and folds the
+several markers a polyglot project has into one entry.</p>
+<p>Without <code>--register</code> it prints what it found and keeps nothing, so a scan can be looked at before it
+becomes registry entries. Registration merges rather than replaces: re-running discovery is how the
+registry stays true, so it has to be safe to repeat, and a machine that is switched off does not
+lose its projects.</p>
+<h2 id="getting-into-a-project"><a class="header" href="#getting-into-a-project">Getting into a project</a></h2>
+<pre><code class="language-sh">wing ssh api                 # a shell in the project, wherever it is
+wing ssh lab:api             # …on that machine specifically
+wing ssh lab                 # just the machine
+wing ssh lab:api -- 'git status'
+wing ssh api --cd src        # start somewhere else
+wing where api               # print the path (local) or the ssh command (remote)
+</code></pre>
+<p><code>wing ssh</code> takes a machine or a project. On a remote project it opens a login shell already inside
+the directory — one lookup and one <code>cd</code>, and it is the same command whether the project turns out to
+be here or three machines away. On a local project it is a shell in that directory.</p>
+<p>A bare name is read as a machine first, since <code>wing ssh lab</code> reads as a machine; <code>--project</code> says
+otherwise and <code>host:name</code> is never ambiguous.</p>
+<p><code>wing where</code> prints instead of entering, which is what a shell function wants:</p>
+<pre><code class="language-sh">cd "$(wing where api)"       # for a local project
+</code></pre>
 <div style="break-before: page; page-break-before: always;"></div><h1 id="machines"><a class="header" href="#machines">Machines</a></h1>
 <p>Machines store SSH targets and host interfaces, and drive a tight SSH
 integration: <code>connect</code>, <code>check --ssh</code>, and <code>sync</code> all reuse one <strong>ControlMaster

projects.html

@@ -161,6 +161,62 @@ <h1 id="projects"><a class="header" href="#projects">Projects</a></h1>
 wing project set api --framework cobra
 wing project discover ~/code --depth 2
 wing project import ~/code --dry-run
+</code></pre>
+<h2 id="where-a-project-lives"><a class="header" href="#where-a-project-lives">Where a project lives</a></h2>
+<p>A project is registered with the machine it is on. Nothing changes for projects on this machine —
+they simply have no host — but once a project is somewhere else, every question about it has two
+halves, and the registry answers both.</p>
+<pre><code class="language-sh">wing project add api --path /srv/api --machine lab
+wing project set api --machine local        # move it back to this machine
+wing project list                           # the Host column
+wing project list --machine lab             # only what is on lab
+wing project list --local
+wing hosts                                  # which machines have projects, and how many
+</code></pre>
+<pre><code> Host   Projects  Languages
+ local  9         nim, go, rust, zig
+ lab    8         go, d, zig, v, rust, cpp, nim
+ build  0
+</code></pre>
+<p>A machine with no projects still gets a row: "nothing here yet" and "no such machine" are different
+answers, and only one of them means you have not run discovery.</p>
+<h3 id="names-are-qualified-by-host"><a class="header" href="#names-are-qualified-by-host">Names are qualified by host</a></h3>
+<p>The same name on two machines is two projects — a <code>deploy</code> on the build server and a <code>deploy</code> here
+are not the same thing, and on a laptop that talks to five servers there will be several such pairs.
+So a project is addressed as <code>name</code>, or as <code>host:name</code> when the bare name is ambiguous:</p>
+<pre><code>$ wing where api
+'api' is on 2 machines: lab:api, local:api — name one of those instead
+</code></pre>
+<p>Both halves of that answer can be typed straight back in. <code>local:</code> names this machine.</p>
+<h2 id="finding-the-projects-on-a-machine"><a class="header" href="#finding-the-projects-on-a-machine">Finding the projects on a machine</a></h2>
+<pre><code class="language-sh">wing project discover ~/code --machine lab --depth 3        # look
+wing project discover ~/code --machine lab --register       # and keep
+wing project discover ~/code --all-machines --register
+wing project discover ~/code --register                     # this machine
+</code></pre>
+<p>One <code>find</code> per machine, run over ssh, all machines at once — a round trip per candidate directory
+would take minutes. It looks for the markers that mean "a project is here" (<code>.git</code>, <code>Cargo.toml</code>,
+<code>go.mod</code>, <code>*.nimble</code>, <code>pyproject.toml</code>, <code>v.mod</code>, <code>*.cabal</code>, <code>.make.lua</code> and the rest) and folds the
+several markers a polyglot project has into one entry.</p>
+<p>Without <code>--register</code> it prints what it found and keeps nothing, so a scan can be looked at before it
+becomes registry entries. Registration merges rather than replaces: re-running discovery is how the
+registry stays true, so it has to be safe to repeat, and a machine that is switched off does not
+lose its projects.</p>
+<h2 id="getting-into-a-project"><a class="header" href="#getting-into-a-project">Getting into a project</a></h2>
+<pre><code class="language-sh">wing ssh api                 # a shell in the project, wherever it is
+wing ssh lab:api             # …on that machine specifically
+wing ssh lab                 # just the machine
+wing ssh lab:api -- 'git status'
+wing ssh api --cd src        # start somewhere else
+wing where api               # print the path (local) or the ssh command (remote)
+</code></pre>
+<p><code>wing ssh</code> takes a machine or a project. On a remote project it opens a login shell already inside
+the directory — one lookup and one <code>cd</code>, and it is the same command whether the project turns out to
+be here or three machines away. On a local project it is a shell in that directory.</p>
+<p>A bare name is read as a machine first, since <code>wing ssh lab</code> reads as a machine; <code>--project</code> says
+otherwise and <code>host:name</code> is never ambiguous.</p>
+<p><code>wing where</code> prints instead of entering, which is what a shell function wants:</p>
+<pre><code class="language-sh">cd "$(wing where api)"       # for a local project
 </code></pre>
 
                     </main>