Struct dt_core::config::Group

pub struct Group<T> where
    T: Operate,  {

    pub global: Rc<GlobalConfig>,
    pub context: Rc<ContextConfig>,
    pub name: GroupName,
    pub scope: DTScope,
    pub base: T,
    pub sources: Vec<T>,
    pub target: PathBuf,
    pub ignored: Option<RenamingRules>,
    pub hostname_sep: Option<HostnameSeparator>,
    pub allow_overwrite: Option<AllowOverwrite>,
    pub ignore_failure: Option<IgnoreFailure>,
    pub method: Option<SyncMethod>,
    pub subgroup_prefix: Option<SubgroupPrefix>,
    pub rename: RenamingRules,
}

Configures how items are grouped.

Fields

global: Rc<GlobalConfig>

The global config object loaded from DT’s config file. This field does not appear in the config file, but is only used by DT internally. Skipping deserializing is achieved via serde’s skip_deserializing attribute, which fills a default value when deserializing.

context: Rc<ContextConfig>

The context config object loaded from config file. Like Group::global, this field does not appear in the config, but is only used by DT internally.

name: GroupName

Name of this group, used as namespace in staging root directory.

scope: DTScope

The priority of this group, used to resolve possibly duplicated items. See DTScope for details.

base: T

The base directory of all source items. This simplifies configuration files with common prefixes in the sources array.

Example

For a directory structure like:

dt/
├── dt-core/
│  └── src/
│     └── config.rs
├── dt-cli/
│  └── src/
│     └── main.rs
└── README.md

Consider the following config file:

[[local]]
base = "dt/dt-cli"
sources = ["*"]
target = "."

It will only sync src/main.rs to the configured target directory (in this case, the directory where DT is being executed).

sources: Vec<T>

Paths (relative to base) to the items to be synced.

target: PathBuf

The path of the parent dir of the final synced items.

Example

source = ["/source/file"]
target = "/tar/get"

will sync /source/file to /tar/get/file (creating non-existing directories along the way), while

source = ["/source/dir"]
target = "/tar/get/dir"

will sync source/dir to /tar/get/dir/dir (creating non-existing directories along the way).

ignored: Option<RenamingRules>

(Optional) Ignored names.

Example

Consider the following ignored setting:

ignored = [".git"]

With this setting, all files or directories with their basename as “.git” will be skipped.

Cannot contain slash in any of the patterns.

hostname_sep: Option<HostnameSeparator>

(Optional) Separator for per-host settings, default to @@.

An additional item with ${hostname_sep}$(hostname) appended to the original item name will be checked first, before looking for the original item. If the appended item is found, use this item instead of the configured one.

Also ignores items that are meant for other hosts by checking if the string after hostname_sep matches current machine’s hostname.

Example

When the following directory structure exists:

~/.ssh/
├── authorized_keys
├── authorized_keys@@sherlock
├── authorized_keys@@watson
├── config
├── config@sherlock
└── config@watson

On a machine with hostname set to watson, the below configuration (extraneous keys are omitted here)

[[local]]
...
hostname_sep = "@@"

base = "~/.ssh"
sources = ["config"]
target = "/tmp/sshconfig"
...

will result in the below target (/tmp/sshconfig):

/tmp/sshconfig/
└── config

Where /tmp/sshconfig/config mirrors the content of ~/.ssh/config@watson.

allow_overwrite: Option<AllowOverwrite>

(Optional) Whether to allow overwriting existing files. Dead symlinks are treated as non-existing, and are always overwritten (regardless of this option).

ignore_failure: Option<IgnoreFailure>

(Optional) Whether to treat errors omitted during syncing of this group as warnings. Note that errors occured before or after syncing are NOT affected.

method: Option<SyncMethod>

(Optional) Syncing method, overrides global.method key.

subgroup_prefix: Option<SubgroupPrefix>

A string to be prepended to a subgroup’s name when creating its staging directory with the Symlink syncing method, overrides global.subgroup_prefix key.

rename: RenamingRules

(Optional) Renaming rules, appends to global.rename.

Implementations

impl<T> Group<T> where
    T: Operate, 

pub fn is_overwrite_allowed(&self) -> bool

Gets the allow_overwrite key from a Group object, falls back to the allow_overwrite from its parent global config.

pub fn is_failure_ignored(&self) -> bool

Gets the ignore_failure key from a Group object, falls back to the ignore_failure from its parent global config.

pub fn get_staging_dir(&self) -> PathBuf

Gets the absolute path to this group’s staging directory, with the subgroup components padded with configured subgroup_prefixes.

pub fn get_method(&self) -> SyncMethod

Gets the method key from a Group object, falls back to the method from its parent global config.

pub fn get_subgroup_prefix(&self) -> String

Gets the subgroup_prefix key from a Group object, falls back to the subgroup_prefix from its parent global config.

pub fn get_hostname_sep(&self) -> String

Gets the hostname_sep key from a Group object, falls back to the hostname_sep from its parent global config.

pub fn get_renaming_rules(&self) -> Vec<RenamingRule>

Gets the list of renaming rules of this group, which is an array of (REGEX, SUBSTITUTION) tuples composed of global.rename and group.rename, used in Operate::make_target to rename the item. The returned list is a combination of the rules from global config and the group’s own rules.

pub fn is_templated(&self) -> bool

Check if this group is templated by checking whether the context section contains this group’s name as a key.

impl Group<PathBuf>

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

Validates this local group, the following cases are denied:

• Checks without querying the filesystem

  1. Empty group name

  2. Source item referencing parent (because items are first populated to the staging directory, and the structure under the staging directory depends on their original relative path to their base)

  3. Current group contains unimplemented ignored field

  4. Target and base are the same

  5. Base contains hostname_sep

  6. Source item is absolute (same reason as above)

  7. Source item contains bad globbing pattern

  8. Source item contains hostname_sep

• Checks that need to query the filesystem

  1. Wrong type of existing staging path (if using the Symlink method)

  2. Path to staging root contains readonly parent directory (if using the Symlink method)

  3. Wrong type of existing target path

  4. Path to target contains readonly parent directory

  5. Base is unreadable

Trait Implementations

impl<T: Clone> Clone for Group<T> where
    T: Operate, 

fn clone(&self) -> Group<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for Group<T> where
    T: Operate, 

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

Formats the value using the given formatter.

impl<T: Default> Default for Group<T> where
    T: Operate, 

fn default() -> Group<T>

Returns the “default value” for a type.

impl<'de, T> Deserialize<'de> for Group<T> where
    T: Operate,
    T: Deserialize<'de>, 

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.