Implement Copy Mode and Refactor Backup/Restore Operations (#2085)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: lra

.github/workflows/install.yaml

@@ -21,6 +21,7 @@ jobs:
           - "3.11"
           - "3.12"
           - "3.13"
+          - "3.14"
     runs-on: ${{ matrix.os }}
     container: python:${{ matrix.python-version }}
     steps:
@@ -34,6 +35,7 @@ jobs:
         os:
           - macos-14
           - macos-15
+          - macos-15-intel
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4

.github/workflows/test.yaml

@@ -17,6 +17,7 @@ jobs:
           - "3.11"
           - "3.12"
           - "3.13"
+          - "3.14"
     steps:
       - uses: actions/checkout@v4
       - uses: astral-sh/setup-uv@v5

INSTALL.md

@@ -1,6 +1,6 @@
 # Detailed install instructions for Mackup
 
-There are 2 ways to run mackup
+There are 2 ways to run mackup:
 
 1. Install it with Homebrew (OSX only)
 2. Install it with PIP (OSX and GNU/Linux)
@@ -19,14 +19,15 @@ mackup -h
 
 ### With Homebrew (OSX only) master branch for latest updates
 
-Want to install latest master releases instead of waiting on homebrew package version?
+Want to install the latest master release instead of waiting on the homebrew
+package version?
 
 [Homebrew reference](https://docs.brew.sh/Manpage#install-options-formulacask)
 
 ```bash
 # Install master
 brew install --HEAD
-# Check if are using the master or stale package
+# Check if you are using the master or stale package
 brew switch mackup <HEAD-XXXX>
 
 mackup -h

README.md

@@ -1,19 +1,16 @@
 # Mackup™
 
-Keep your application settings in sync.
+Backup and keep your application settings in sync.
 
 ## Table of contents
 
 - [Mackup](#mackup)
   - [Table of contents](#table-of-contents)
-  - [WARNING](#warning)
   - [Quickstart](#quickstart)
   - [Usage](#usage)
   - [What does it do](#what-does-it-do)
-  - [Bullsh\*t, what does it really do to my files](#bullsht-what-does-it-really-do-to-my-files)
-    - [Backup](#backup)
-    - [Restore](#restore)
-    - [Uninstall](#uninstall)
+    - [Copy mode](#copy-mode)
+    - [Link mode](#link-mode)
   - [Supported Storages](#supported-storages)
   - [Unsupported Storages](#unsupported-storages)
   - [Supported Applications](#supported-applications)
@@ -24,19 +21,8 @@ Keep your application settings in sync.
   - [What's up with the weird name](#whats-up-with-the-weird-name)
   - [Where can I find more information](#where-can-i-find-more-information)
 
-## WARNING
-
-⚠️ Mackup does not work correctly in macOS Sonoma and all later versions,
-since it does not support symlinked files for preferences. Running this code
-will destroy all user preferences without a means for recovery. For more
-information, see issues [#1924](https://github.com/lra/mackup/issues/1924)
-and [2035](https://github.com/lra/mackup/issues/2035).
-
 ## Quickstart
 
-If you have [Dropbox](https://www.dropbox.com) installed and want to use it to
-save your config files, that's super easy.
-
 On macOS, if you want an easy install, you can install
 [Homebrew](http://brew.sh/) and do:
 
@@ -50,10 +36,6 @@ mackup backup
 
 If not running macOS, or you don't like Homebrew, you can use [pip](https://pip.pypa.io/en/stable/).
 
-> Note: The below command will check if a previous version of Mackup
-> is already installed on your system.
-> If this is the case, it will be upgraded to the latest version.
-
 ```bash
 # Install Mackup with PIP
 pip install --upgrade mackup
@@ -62,13 +44,7 @@ pip install --upgrade mackup
 mackup backup
 ```
 
-> On **Ubuntu**, pip will install to the current user's home
-> directory rather than system-wide. Because of this, when
-> installing pip on **Ubuntu** you will need to run `pip install`
-> with the `--system` flag as well (on other platforms this is not
-> needed)
-
-You're all set and constantly backed up from now on.
+You're all set and can back up from now on.
 
 Next, on any new workstation, do:
 
@@ -88,15 +64,26 @@ You can find more detailed instructions in [INSTALL.md](INSTALL.md).
 
 `mackup backup`
 
-Backup your application settings.
+Back up your application files. Copy your local config files into the Mackup folder.
 
 `mackup restore`
 
 Restore your application settings on a newly installed workstation.
+Copy config files from the Mackup folder to your home folder.
+
+`mackup link install`
 
-`mackup uninstall`
+Move your local config files into the Mackup folder,
+and link them to their original place.
+
+`mackup link`
+
+On another workstation, links local config files from the Mackup folder.
+
+`mackup link uninstall`
 
 Copy back any synced config file to its original place.
+Removes the links and copies config files from the Mackup folder back into your home.
 
 `mackup list`
 
@@ -108,49 +95,73 @@ Get some help, obviously...
 
 ## What does it do
 
-- Back ups your application settings in a safe directory (e.g. Dropbox)
-- Syncs your application settings among all your workstations
-- Restores your configuration on any fresh install in one command line
-
 By only tracking pure configuration files, it keeps the crap out of your
 freshly new installed workstation (no cache, temporary and locally specific
-files are transfered).
+files are transferred).
 
-Mackup makes setting up the environment easy and simple, saving time for your
-family, great ideas, and all the cool stuff you like.
+Mackup makes setting up the environment easy and simple.
 
-## Bullsh\*t, what does it really do to my files
+There are 2 modes of operations: copy mode and link mode.
+
+### Copy mode
+
+Copy mode is used to back up and restore your files.
+The files are backed up into the configured Mackup folder,
+which can be in Dropbox, iCloud, or wherever you configure it.
+
+It is covered by the 2 commands:
+
+- `mackup backup`
+- `mackup restore`
+
+### Link mode
+
+Link mode is used to move your config files into the Mackup folder,
+and link them back to their original place.
+
+This mode is useful if you are using multiple workstations,
+and want to keep your application settings in sync at all times.
+
+- Backs up your application settings in a safe directory (e.g. Dropbox)
+- Syncs your application settings among all your workstations
+- Restores your configuration on any fresh install in one command line
 
 Let's take `git` as an example. Your settings for `git` are saved in your home
 folder, in the `.gitconfig` file.
 
-### Backup
+It is covered by the 3 commands:
+
+- `mackup link install`
+- `mackup link`
+- `mackup link uninstall`
+
+#### `mackup link install`
 
-If you have Dropbox, these things happen when you launch `mackup backup`:
+If you have Dropbox, these things happen when you launch `mackup link install`:
 
 1. `cp ~/.gitconfig ~/Dropbox/Mackup/.gitconfig`
 2. `rm ~/.gitconfig`
 3. `ln -s ~/Dropbox/Mackup/.gitconfig ~/.gitconfig`
 
 Now your `git` config is always backed up and up to date on all your workstations.
 
-### Restore
+#### `mackup link`
 
-When you launch `mackup restore`, here's what it's really doing:
+When you launch `mackup link`, here's what it's really doing:
 
 1. `ln -s ~/Dropbox/Mackup/.gitconfig ~/.gitconfig`
 
 That's it, you got your `git` config setup on your new workstation.
 
 `mackup` does the same for any supported application.
 
-### Uninstall
+#### `mackup link uninstall`
 
 You can revert all your files to their original state.
 
 ```bash
 # Just run this
-mackup uninstall
+mackup link uninstall
 ```
 
 This will remove the symlinks and copy back the files from the Mackup folder in

doc/README.md

@@ -39,14 +39,20 @@ engine = google_drive
 
 ### iCloud
 
-If you choose the `iCloud` storage engine, Mackup will store store your
+If you choose the `iCloud` storage engine, Mackup will store your
 configuration files in the `~/Library/Mobile\ Documents/com\~apple\~CloudDocs/` folder.
 
 ```ini
 [storage]
 engine = icloud
 ```
 
+You can check if your files are synced using:
+
+```sh
+brctl monitor com.apple.CloudDocs
+```
+
 ### File System
 
 If you want to specify another directory, you can use the `file_system` engine
@@ -64,7 +70,7 @@ path = some/folder/in/your/home
 ```
 
 Note: you don't need to escape spaces or wrap the path in quotes.
-For example, the following paths are valid :
+For example, the following paths are valid:
 
 ```ini
 path = some/path in your/home
@@ -73,7 +79,7 @@ path = /some path/in/your/root
 
 ### Custom Directory Name
 
-You can customize the directory name in which Mackup stores your file. By
+You can customize the directory name in which Mackup stores your files. By
 default, if not specified, Mackup creates a `Mackup` directory in the storage
 engine you chose, e.g. `~/Dropbox/Mackup`.
 
@@ -116,7 +122,7 @@ already setup (ex: from `dropbox` to `icloud`), complete the following steps.
 ### Only sync one or two applications
 
 In your home folder, create a file named `.mackup.cfg` and add the application
-names to allow in the `[applications_to_sync]` section, one by line.
+names to allow in the `[applications_to_sync]` section, one per line.
 
 ```ini
 # Example, to only sync SSH and Adium:
@@ -129,7 +135,7 @@ Use `mackup list` to get a list of valid application names. Don't use fancy
 names (with spaces) here.
 
 A [sample](.mackup.cfg) of this file is available in this folder. Just copy it
-in your home folder:
+to your home folder:
 
 ```bash
 cp mackup/doc/.mackup.cfg ~/
@@ -138,7 +144,7 @@ cp mackup/doc/.mackup.cfg ~/
 ### Don't sync an application
 
 In your home folder, create a file named `.mackup.cfg` and add the application
-names to ignore in the `[applications_to_ignore]` section, one by line.
+names to ignore in the `[applications_to_ignore]` section, one per line.
 
 ```ini
 # Example, to not sync SSH and Adium:
@@ -151,7 +157,7 @@ Use `mackup list` to get a list of valid application names. Don't use fancy
 names (with spaces) here.
 
 A [sample](.mackup.cfg) of this file is available in this folder. Just copy it
-in your home folder:
+to your home folder:
 
 ```bash
 cp mackup/doc/.mackup.cfg ~/
@@ -172,7 +178,7 @@ to get your Pull Request merged faster.
 You can customize the Mackup engine and add support for unsupported
 applications or just custom files and directories you'd like to sync.
 
-NOTE: Files and directory to be synced should be rooted at $HOME.
+NOTE: Files and directories to be synced should be rooted at $HOME.
 
 Let's say that you'd like to add support for Nethack (config file:
 `.nethackrc`) and for the `bin` and `.hidden` directories you keep in your
@@ -187,7 +193,7 @@ touch ~/.mackup/nethack.cfg
 touch ~/.mackup/my-files.cfg
 ```
 
-Edit those files
+Edit those files:
 
 ```bash
 $ nano ~/.mackup/nethack.cfg
@@ -228,7 +234,7 @@ mackup backup
 If you override an application config that is already supported by Mackup, your
 new config for this application will replace the one provided by Mackup.
 
-You can find some sample config in this directory.
+You can find some sample configs in this directory.
 
 ### Locally test an application before submitting a Pull Request
 
@@ -246,14 +252,14 @@ You can add and test an application by following these steps:
 
 ### Add support for an application using the XDG directory
 
-For application storing their configuration under the `~/.config` folder, you
+For applications storing their configuration under the `~/.config` folder, you
 should not hardcode it. The `.config` folder is the default location but it can
 be named differently on other users' systems by setting the `XDG_CONFIG_HOME`
 environment variable.
 
 See <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>
 
-Mackup supports this mechanism and provide a dedicated `xdg_configuration_files`
+Mackup supports this mechanism and provides a dedicated `xdg_configuration_files`
 section for those applications.
 
 If any path starts with `.config`, remove the `.config` part and move the path