Struct SshConfigFile 

pub struct SshConfigFile {
    pub elements: Vec<ConfigElement>,
    pub path: PathBuf,
    pub crlf: bool,
    pub bom: bool,
}

Represents the entire SSH config file as a sequence of elements. Preserves the original structure for round-trip fidelity.

Fields

elements: Vec<ConfigElement>

path: PathBuf

crlf: bool

Whether the original file used CRLF line endings.

bom: bool

Whether the original file started with a UTF-8 BOM.

Implementations

impl SshConfigFile

pub fn host_entries(&self) -> Vec<HostEntry>

Get all host entries as convenience views (including from Include files).

pub fn include_paths(&self) -> Vec<PathBuf>

Collect all resolved Include file paths (recursively).

pub fn include_glob_dirs(&self) -> Vec<PathBuf>

Collect parent directories of Include glob patterns. When a file is added/removed under a glob dir, the directory’s mtime changes.

pub fn remove_all_orphaned_group_headers(&mut self) -> usize

Remove # purple:group <Name> headers that have no corresponding provider hosts. Returns the number of headers removed.

pub fn repair_absorbed_group_comments(&mut self) -> usize

Repair configs where # purple:group comments were absorbed into the preceding host block’s directives instead of being stored as GlobalLines. Returns the number of blocks that were repaired.

pub fn has_host(&self, alias: &str) -> bool

Check if a host alias already exists (including in Include files). Walks the element tree directly without building HostEntry structs.

pub fn is_included_host(&self, alias: &str) -> bool

Check if a host alias is from an included file (read-only). Handles multi-pattern Host lines by splitting on whitespace.

pub fn add_host(&mut self, entry: &HostEntry)

Add a new host entry to the config. Inserts before any trailing wildcard/pattern Host blocks (e.g. Host *) so that SSH “first match wins” semantics are preserved. If wildcards are only at the top of the file (acting as global defaults), appends at end.

pub fn last_element_has_trailing_blank(&self) -> bool

Check if the last element already ends with a blank line.

pub fn update_host(&mut self, old_alias: &str, entry: &HostEntry)

Update an existing host entry by alias. Merges changes into the existing block, preserving unknown directives.

pub fn set_host_provider( &mut self, alias: &str, provider_name: &str, server_id: &str, )

Set provider on a host block by alias.

pub fn find_hosts_by_provider( &self, provider_name: &str, ) -> Vec<(String, String)>

Find all hosts with a specific provider, returning (alias, server_id) pairs. Searches both top-level elements and Include files so that provider hosts in included configs are recognized during sync (prevents duplicate additions).

pub fn add_forward(&mut self, alias: &str, directive_key: &str, value: &str)

Add a forwarding directive to a host block. Inserts at content_end() (before trailing blanks), using detected indentation. Uses split_whitespace matching for multi-pattern Host lines.

pub fn remove_forward( &mut self, alias: &str, directive_key: &str, value: &str, ) -> bool

Remove a specific forwarding directive from a host block. Matches key (case-insensitive) and value (whitespace-normalized). Uses split_whitespace matching for multi-pattern Host lines. Returns true if a directive was actually removed.

pub fn has_forward(&self, alias: &str, directive_key: &str, value: &str) -> bool

Check if a host block has a specific forwarding directive. Uses whitespace-normalized value comparison and split_whitespace host matching.

pub fn find_tunnel_directives(&self, alias: &str) -> Vec<TunnelRule>

Find tunnel directives for a host alias, searching all elements including Include files. Uses split_whitespace matching like has_host() for multi-pattern Host lines.

pub fn deduplicate_alias(&self, base: &str) -> String

Generate a unique alias by appending -2, -3, etc. if the base alias is taken.

pub fn deduplicate_alias_excluding( &self, base: &str, exclude: Option<&str>, ) -> String

Generate a unique alias, optionally excluding one alias from collision detection. Used during rename so the host being renamed doesn’t collide with itself.

pub fn set_host_tags(&mut self, alias: &str, tags: &[String])

Set tags on a host block by alias.

pub fn set_host_askpass(&mut self, alias: &str, source: &str)

Set askpass source on a host block by alias.

pub fn set_host_meta(&mut self, alias: &str, meta: &[(String, String)])

Set provider metadata on a host block by alias.

pub fn delete_host(&mut self, alias: &str)

Delete a host entry by alias.

pub fn delete_host_undoable( &mut self, alias: &str, ) -> Option<(ConfigElement, usize)>

Delete a host and return the removed element and its position for undo. Does NOT collapse blank lines or remove group headers so the position stays valid for re-insertion via insert_host_at(). Orphaned group headers (if any) are cleaned up at next startup.

pub fn insert_host_at(&mut self, element: ConfigElement, position: usize)

Insert a host block at a specific position (for undo).

pub fn find_provider_insert_position( &self, provider_name: &str, ) -> Option<usize>

Find the position after the last HostBlock that belongs to a provider. Returns None if no hosts for this provider exist in the config. Used by the sync engine to insert new hosts adjacent to existing provider hosts.

pub fn swap_hosts(&mut self, alias_a: &str, alias_b: &str) -> bool

Swap two host blocks in the config by alias. Returns true if swap was performed.

impl SshConfigFile

pub fn parse(path: &Path) -> Result<Self>

Parse an SSH config file from the given path. Preserves all formatting, comments, and unknown directives for round-trip fidelity.

pub fn parse_content(content: &str) -> Vec<ConfigElement>

Parse SSH config content from a string (without Include resolution). Used by tests to create SshConfigFile from inline strings.

impl SshConfigFile

pub fn write(&self) -> Result<()>

Write the config back to disk. Creates a backup before writing and uses atomic write (temp file + rename). Resolves symlinks so the rename targets the real file, not the link. Acquires an advisory lock to prevent concurrent writes from multiple purple processes or background sync threads.

pub fn serialize(&self) -> String

Serialize the config to a string. Collapses consecutive blank lines to prevent accumulation after deletions.

Trait Implementations

impl Clone for SshConfigFile

fn clone(&self) -> SshConfigFile

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SshConfigFile

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.