Disabling targets

README.md

@@ -51,7 +51,7 @@ api-key: <<API-KEY()>>
 
 ```
 
-(Note the parenteses in `API-KEY()`).
+(Note the parentheses in `API-KEY()`).
 
 ## Limitations
 
@@ -124,7 +124,7 @@ parallel, though I haven't identified yet how to best do this.
 
 ### Tangling
 
-Tangling obeys the same target tags. This will create `~/foo.txt` in `server1`:
+Tangling obeys the same targets. This will create `~/foo.txt` in `server1`:
 
 ```
 * Upload a file to server1                              :server1:
@@ -145,6 +145,50 @@ You can tangle a file to multiple servers. This will create `~/foo.txt` on both
 #+END_SRC
 ```
 
+Given
+
+`#+TARGET: /ssh:example1.com:/opt/app (server1)`,
+
+`:tangle` resolves to a path within the host:
+
+| `:tangle`        | resolves to                               |
+|------------------|-------------------------------------------|
+| `foo.txt`        | `/ssh:example1.com:/opt/app/foo.txt`      |
+| `conf/foo.txt`   | `/ssh:example1.com:/opt/app/conf/foo.txt` |
+| `./conf/foo.txt` | same as above — the `./` is dropped       |
+| `/etc/foo.txt`   | `/ssh:example1.com:/etc/foo.txt`          |
+| `~/foo.txt`      | `/ssh:example1.com:~/foo.txt`             |
+
+## Disabling with :target nil
+
+Sometimes you may want to "turn off" the target for a single block.
+
+As an example, let's say we have a container `TARGET`:
+
+```
+#+TARGET: /ssh:server.com|podman:my-container: (container)
+```
+
+We can filter the results locally by adding `target: nil` to a second block:
+
+```
+* Service status                                      :container:
+
+#+NAME: status
+#+BEGIN_SRC sh
+some-cli status --json
+#+END_SRC
+
+#+BEGIN_SRC sh :stdin status :target nil
+jq -r '.services
+  | to_entries[]
+  | select(.value.state != "running")
+  | "\(.key)\t\(.value.state)\t\(.value.health)"'
+#+END_SRC
+```
+
+This will work even if the `jq` command is not installed in the container :)
+
 ## Drift detection
 
 Tangling pushes the org file out to its targets. `devops-drift` asks the

devops-drift.el

@@ -64,8 +64,16 @@ original :tangle value, LOCAL the rewritten local file and REMOTE the
 file the path denotes at TARGET.  A PATH that is already a TRAMP path
 keeps itself as REMOTE but is still redirected to LOCAL-ROOT: a drift
 check must never write to a remote.  Skips :tangle no and :tangle yes.
+
+A block that opted out with `:target nil' has no target to be compared
+against, so it is left out of the mapping and its header is neutralized
+to :tangle no.  Neutralizing it matters as much as omitting it: the
+block's own path is a real local file, and tangling it here would make a
+read-only check write to the user's filesystem.
+
 Modifies buffer text."
-  (let (mapping)
+  (let ((opted-out (devops--target-opted-out-regions))
+        mapping)
     (save-excursion
       (goto-char (point-max))
       (while (re-search-backward ":tangle +\\([^ \t\n]+\\)" nil t)
@@ -76,18 +84,23 @@ Modifies buffer text."
               (end (match-end 0))
               (path (match-string 1)))
           (unless (member path '("no" "yes"))
-            (let ((remote (if (tramp-tramp-file-p path)
-                              path
-                            (devops--join-target target path)))
-                  (local (expand-file-name
-                          (devops--drift-localize-path path) local-root)))
-              (delete-region beg end)
-              (goto-char beg)
-              (insert ":tangle " local)
-              ;; Step before the rewrite so the backward search keeps
-              ;; making progress (the rewritten path matches the regexp).
-              (goto-char beg)
-              (push (list path local remote) mapping))))))
+            (if (devops--in-regions-p beg opted-out)
+                (progn
+                  (delete-region beg end)
+                  (goto-char beg)
+                  (insert ":tangle no"))
+              (let ((remote (if (tramp-tramp-file-p path)
+                                path
+                              (devops--join-target target path)))
+                    (local (expand-file-name
+                            (devops--drift-localize-path path) local-root)))
+                (delete-region beg end)
+                (goto-char beg)
+                (insert ":tangle " local)
+                (push (list path local remote) mapping)))
+            ;; Step before the rewrite so the backward search keeps
+            ;; making progress (the rewritten path matches the regexp).
+            (goto-char beg)))))
     mapping))
 
 (defun devops--drift-tangle-heading (source-buf heading-pos tag target local-root)