# Asymmetric Synchronization Functions

    library(syncdr)
    #devtools::load_all(".")

    # Create .syncdrenv
    .syncdrenv = toy_dirs()
    #> ■■■■■■■■■■■■■■■                   47% | ETA:  5s
    #> ■■■■■■■■■■■■■■■■■■■■■■■■■■■       87% | ETA:  1s

    # Get left and right directories' paths
    left  <- .syncdrenv$left
    right <- .syncdrenv$right

This article covers functions designed for asymmetric synchronization between two directories.

## What is asymmetric synchronization?

This is a one-way synchronization: you have a master/leader directory, and you want changes made there to be reflected in a secondary/follower directory.

⏭️ For all synchronization functions below, note that synchronization occurs from left to right. This mean that the right directory will mirror the contents of the left directory.

Key Points:

When using these synchronization functions, you have two options for providing inputs:

1. Specify the paths for both the left and right directories, and set the `by_date` and `by_content` arguments as desired (default: `by_date = TRUE` and `by_content = FALSE`).

2. First, use the `compare_directories()` function to generate a sync_status object. Then, provide this object as input to the synchronization function. The `by_date` and `by_content` arguments will be automatically determined based on the `sync_status`.

## Types of asymmetric synchronization

`syncdr` allows to perform a specific set of asymmetric synchronization actions, so that you can choose which one to execute depending on your needs

Types of asymmetric synchronization
Type of synchronization | Actions on common files | Actions on non-common files
--- | --- | ---
Full asymmetric synchronization: `full_asym_sync_to_right()` | If comparing by date only (`by_date = TRUE`): Copy files that are newer in the left directory to the right directory. If comparing by date and content (`by_date = TRUE` and `by_content = TRUE`): Copy files that are newer and different in the left directory to the right directory. If comparing by content only (`by_content = TRUE`): Copy files that are different in the left directory to the right directory | Copy to the right directory those files that exist only in the left directory. Delete from the right directory those files that are exclusive in the right directory (i.e., missing in the left directory)
Partial asymmetric synchronization -common files: `common_files_asym_sync_to_right()` | if `by_date = TRUE` only: copy files that are newer in left to right if `by date = TRUE` and `by_content = TRUE`: copy files that are newer and different in left to right if `by_content = TRUE` only: copy files that are different in left to right | no actions
Full asymmetric synchronization of non common files `update_missing_files_asym_to_right()` | no actions | copy those files that are only in left to right delete in right those files that are only in right (i.e., files “only in right” or in other words missing in left)
Partial asymmetric asymmetric synchronization of non common files: `partial_update_missing_files_asym_to_right()` | no actions | copy those files that are only in left to right keep in right those files that are only in right (i.e., files ‘missing in left’)

Let’s see them in actions through the examples below:

##### *️⃣ Note: `verbose = TRUE`

When executing any synchronization, you have the option to enable verbose mode by setting `verbose = TRUE`. This will display the tree structure of both directories BEFORE and AFTER the synchronization

1 - Full asymmetric synchronization:

    # With leader/master directory being the left directory
    # Option 1
    full_asym_sync_to_right(left_path  = left,
                            right_path = right,
                            by_content = TRUE)
    #>
    #>
    #> |Files               |Action        |
    #> |:-------------------|:-------------|
    #> |/C/C1_duplicate.Rds |To be deleted |
    #> |/D/D3.Rds           |To be deleted |
    #> |/E/E1.Rds           |To be deleted |
    #> |/E/E2.Rds           |To be deleted |
    #> |/E/E3.Rds           |To be deleted |
    #> These files will be COPIED (overwriting if present) to right
    #>
    #>
    #> |Files     |Action       |
    #> |:---------|:------------|
    #> |/D/D1.Rds |To be copied |
    #> |/D/D2.Rds |To be copied |
    #> |/A/A1.Rds |To be copied |
    #> |/A/A2.Rds |To be copied |
    #> |/A/A3.Rds |To be copied |
    #> |/B/B3.Rds |To be copied |
    #> Do you want to proceed? Type your answer (Yes/no/cancel)
    #> ✔ synchronized
    # Option 2
    sync_status <- compare_directories(left_path  = left,
                                       right_path = right,
                                       by_content = TRUE)

    full_asym_sync_to_right(sync_status = sync_status)
    #>
    #>
    #> |Files               |Action        |
    #> |:-------------------|:-------------|
    #> |/C/C1_duplicate.Rds |To be deleted |
    #> |/D/D3.Rds           |To be deleted |
    #> |/E/E1.Rds           |To be deleted |
    #> |/E/E2.Rds           |To be deleted |
    #> |/E/E3.Rds           |To be deleted |
    #> Do you want to proceed? Type your answer (Yes/no/cancel)
    #> ✔ synchronized

    # With leader/master directory being the right directory
    sync_status <- compare_directories(left_path  = right,  #notice args changing here
                                       right_path = left,
                                       by_content = TRUE)

    full_asym_sync_to_right(sync_status = sync_status)
    #> These files will be COPIED (overwriting if present) to right
    #>
    #>
    #> |Files               |Action       |
    #> |:-------------------|:------------|
    #> |/B/B1.Rds           |To be copied |
    #> |/B/B2.Rds           |To be copied |
    #> |/C/C2.Rds           |To be copied |
    #> |/C/C3.Rds           |To be copied |
    #> |/C/C1_duplicate.Rds |To be copied |
    #> |/D/D3.Rds           |To be copied |
    #> |/E/E1.Rds           |To be copied |
    #> |/E/E2.Rds           |To be copied |
    #> |/E/E3.Rds           |To be copied |
    #> Do you want to proceed? Type your answer (Yes/no/cancel)
    #> ✔ synchronized

2 - Partial asymmetric synchronization -common files:

    sync_status <- compare_directories(left_path  = left,
                                       right_path = right)

    common_files_asym_sync_to_right(sync_status = sync_status)
    #> Do you want to proceed? Type your answer (Yes/no/cancel)
    #> ✔ synchronized

3 - Full asymmetric synchronization -non common files:

    sync_status <- compare_directories(left_path  = left,
                                       right_path = right)

    update_missing_files_asym_to_right(sync_status = sync_status)
    #> Do you want to proceed? Type your answer (Yes/no/cancel)
    #> ✔ synchronized

4 - Partial asymmetric synchronization -non common files:

    sync_status <- compare_directories(left_path  = left,
                                       right_path = right)

    partial_update_missing_files_asym_to_right(sync_status = sync_status)
    #> Do you want to proceed? Type your answer (Yes/no/cancel)
    #> ✔ synchronized

## Synchronizing Using Additional Options

To retain more control over the synchronization process, you can utilize two additional options available for all synchronization functions: backup and force.

- Backup Option: Setting `backup = TRUE` will create a backup (copy) of the right directory before performing the synchronization. This backup is stored in the location specified by `backup_dir`. If `backup_dir` is not provided, the backup will be saved in a temporary directory (`tempdir`). This ensures that you can revert to the previous state if needed

- Force Option: By default, force = TRUE, which means the function will proceed directly with the synchronization without any interruptions. If you set force = FALSE, the function will first display a preview of the proposed actions, including which files will be copied and which will be deleted. You will be prompted to confirm whether you wish to proceed with these actions. Synchronization will only continue if you agree; otherwise, it will be aborted, and no changes will be made to the directories.