# filesystem::tree

> Tag 3: the client names the paths to leave out; the server sends the filesystem of the container from its root as a snapshot and one response per change, until the client stops it or the server ends.

Canonical: https://protocol.diverge.network/2.3.0/container-proxy-endpoints/filesystem-tree/
Specification revision: 2.3.0

The client opens the scope with a request whose payload is the tag
byte `3` followed by the paths to leave out, as JSON. The server sends
the tree as a snapshot, one response, and after it one response per
change, for as long as the scope lives; the client asks for the end
by opening one channel on it, the stop, and the server ends the scope
by the response finish.

- **The request.** [Request](/2.3.0/container-proxy-endpoints/filesystem-tree/request/) states its form.
- **The response.** [Response](/2.3.0/container-proxy-endpoints/filesystem-tree/response/) states the sequence of
  the main stream.
- **The channels.** The client opens the channel that
  [Client Channels](/2.3.0/container-proxy-endpoints/filesystem-tree/client/) defines. The server opens no channel
  on a tree scope.

## The order

1. **The server reads the request.** A request whose payload does not
   decode is answered by a response finish that no response precedes,
   as [Container Proxy Endpoints](/2.3.0/container-proxy-endpoints/) provides.
2. **The server watches, and walks.** The watch is armed before the
   walk, so that a change during the walk is sent after the snapshot
   rather than lost. A watch that cannot be made, a root that cannot
   be watched, or a walk that dies is answered by exactly one error
   response and the finish.
3. **The server sends the snapshot.** Exactly one response carrying the
   whole tree, first.
4. **The server sends every change.** One response per change, in the
   order the changes were observed. A directory the server could not
   watch is present in the tree with `changes` false, and no change
   under it is sent. Lost events — an overflowed queue — are answered
   by a fresh snapshot on the same scope, not by an error.
5. **The server answers the stop.** It sends the response finish after
   it receives the stop, and drops the watch.

## The rules that hold throughout

- **Left out.** `/proc`, `/sys` and `/dev` are left out of every tree,
  and every path the request names. A path left out is absent from
  the snapshot, never watched, and a change under it is not sent.
- **The form.** Each response carries one frame of the
  [filetree](/2.3.0/endpoints/containers-agents-run/client/filetree/)
  stream, as that channel defines it, over the root of the container.
- **No timeout.** The server imposes no timeout on the scope.