github.com/jstaf/onedriver@v0.14.2-0.20240420231225-f07678f9e6ef/README.md (about) 1 [](https://github.com/jstaf/onedriver/actions?query=workflow%3A%22Run+tests%22) 2 [](https://coveralls.io/github/jstaf/onedriver?branch=master) 3 [](https://copr.fedorainfracloud.org/coprs/jstaf/onedriver/package/onedriver/) 4 5 # onedriver 6 7 **onedriver is a native Linux filesystem for Microsoft OneDrive.** 8 9 onedriver is a network filesystem that gives your computer direct access to your 10 files on Microsoft OneDrive. This is not a sync client. Instead of syncing 11 files, onedriver performs an on-demand download of files when your computer 12 attempts to use them. onedriver allows you to use files on OneDrive as if they 13 were files on your local computer. 14 15 onedriver is extremely straightforwards to use: 16 17 - Install onedriver using your favorite installation method. 18 - Click the "+" button in the app to setup one or more OneDrive accounts. 19 (There's a command-line workflow for those who prefer doing things that way 20 too!) 21 - Just start using your files on OneDrive as if they were normal files. 22 23 I've spent a lot of time trying to make onedriver fast, convenient, and easy to 24 use. Though you can use it on servers, the goal here is to make it easy to work 25 with OneDrive files on your Linux desktop. This allows you to easily sync files 26 between any number of Windows, Mac, and Linux computers. You can setup your 27 phone to auto-upload photos to OneDrive and edit and view them on your Linux 28 computer. You can switch between LibreOffice on your local computer and the 29 Microsoft 365 online apps as needed when working. Want to migrate from Windows 30 to Linux? Just throw all your Windows files into OneDrive, add your OneDrive 31 account to Linux with onedriver, and call it a day. 32 33 **Microsoft OneDrive works on Linux.** 34 35 Getting started with your files on OneDrive is as easy as running: 36 `onedriver /path/to/mount/onedrive/at` (there's also a helpful GUI!). To get a 37 list of all the arguments onedriver can be run with you can read the manual page 38 by typing `man onedriver` or get a quick summary with `onedriver --help`. 39 40 ## Key features 41 42 onedriver has several nice features that make it significantly more useful than 43 other OneDrive clients: 44 45 - **Files are only downloaded when you use them.** onedriver will only download 46 a file if you (or a program on your computer) uses that file. You don't need 47 to wait hours for a sync client to sync your entire OneDrive account to your 48 local computer or try to guess which files and folders you might need later 49 while setting up a "selective sync". onedriver gives you instant access to 50 _all_ of your files and only downloads the ones you use. 51 52 - **Bidirectional sync.** Although onedriver doesn't actually "sync" any files, 53 any changes that occur on OneDrive will be automatically reflected on your 54 local machine. onedriver will only redownload a file when you access a file 55 that has been changed remotely on OneDrive. If you somehow simultaneously 56 modify a file both locally on your computer and also remotely on OneDrive, 57 your local copy will always take priority (to avoid you losing any local 58 work). 59 60 - **Can be used offline.** Files you've opened previously will be available even 61 if your computer has no access to the internet. The filesystem becomes 62 read-only if you lose internet access, and automatically enables write access 63 again when you reconnect to the internet. 64 65 - **Fast.** Great care has been taken to ensure that onedriver never makes a 66 network request unless it actually needs to. onedriver caches both filesystem 67 metadata and file contents both in memory and on-disk. Accessing your OneDrive 68 files will be fast and snappy even if you're engaged in a fight to the death 69 for the last power outlet at a coffeeshop with bad wifi. (This has definitely 70 never happened to me before, why do you ask?) 71 72 - **Has a user interface.** You can add and remove your OneDrive accounts 73 without ever using the command-line. Once you've added your OneDrive accounts, 74 there's no special interface beyond your normal file browser. 75 76 - **Free and open-source.** They're your files. Why should you have to pay to 77 access them? onedriver is licensed under the GPLv3, which means you will 78 _always_ have access to use onedriver to access your files on OneDrive. 79 80 ## Quick start 81 82 ### Fedora/CentOS/RHEL 83 84 Users on Fedora/CentOS/RHEL systems are recommended to install onedriver from 85 [COPR](https://copr.fedorainfracloud.org/coprs/jstaf/onedriver/). This will 86 install the latest version of onedriver through your package manager and ensure 87 it stays up-to-date with bugfixes and new features. 88 89 ```bash 90 sudo dnf copr enable jstaf/onedriver 91 sudo dnf install onedriver 92 ``` 93 94 ### OpenSUSE 95 96 OpenSUSE users need to add the COPR repo either for Leap or Tumbleweed 97 98 ```bash 99 # Leap 15.4 100 sudo zypper addrepo -g -r https://copr.fedorainfracloud.org/coprs/jstaf/onedriver/repo/opensuse-leap-15.4/jstaf-onedriver-opensuse-leap-15.4.repo onedriver 101 sudo zypper --gpg-auto-import-keys refresh 102 sudo zypper install onedriver 103 104 # Tumbleweed 105 sudo zypper addrepo -g -r https://copr.fedorainfracloud.org/coprs/jstaf/onedriver/repo/opensuse-tumbleweed/jstaf-onedriver-opensuse-tumbleweed.repo onedriver 106 sudo zypper --gpg-auto-import-keys refresh 107 sudo zypper install onedriver 108 ``` 109 110 ### Ubuntu/Pop!\_OS/Debian 111 112 Ubuntu/Pop!\_OS/Debian users can install onedriver from the 113 [OpenSUSE Build Service](https://software.opensuse.org/download.html?project=home%3Ajstaf&package=onedriver) 114 (despite the name, OBS also does a nice job of building packages for Debian). 115 Like the COPR install, this will enable you to install onedriver through your 116 package manager and install updates as they become available. If you previously 117 installed onedriver via PPA, you can purge the old PPA from your system via: 118 `sudo add-apt-repository --remove ppa:jstaf/onedriver` 119 120 ### Arch/Manjaro/EndeavourOS 121 122 Arch/Manjaro/EndeavourOS users can install onedriver from the 123 [AUR](https://aur.archlinux.org/packages/onedriver/). 124 125 Post-installation, you can start onedriver either via the `onedriver-launcher` 126 desktop app, or via the command line: `onedriver /path/to/mount/onedrive/at/`. 127 128 ### Gentoo 129 130 Gentoo users can install onedriver from 131 [this ebuild overlay](https://github.com/foopsss/gentoo-overlay) provided by a user. If 132 you don't want to add user-hosted overlays to your system you may copy the 133 ebuild for the latest version to a local overlay, which can be created by 134 following the instructions available in the 135 [Gentoo Wiki](https://wiki.gentoo.org/wiki/Creating_an_ebuild_repository). 136 137 Make sure to carefully review the ebuild for the package before installing it 138 139 ### NixOS/NixPkgs 140 141 NixOS and Nix users can install onedriver from 142 [the unstable channel](https://search.nixos.org/packages?channel=unstable&query=onedriver) 143 either by adding the package to their system's configuration (if they are using 144 NixOS) or by installing it manually via `nix-env -iA unstable.onedriver`. 145 146 ## Multiple drives and starting OneDrive on login via systemd 147 148 **Note:** You can also set this up through the GUI via the `onedriver-launcher` 149 desktop app installed via rpm/deb/`make install`. You can skip this section if 150 you're using the GUI. It's honestly easier. 151 152 To start onedriver automatically and ensure you always have access to your 153 files, you can start onedriver as a systemd user service. In this example, 154 `$MOUNTPOINT` refers to where we want OneDrive to be mounted at (for instance, 155 `~/OneDrive`). 156 157 ```bash 158 # create the mountpoint and determine the service name 159 mkdir -p $MOUNTPOINT 160 export SERVICE_NAME=$(systemd-escape --template onedriver@.service --path $MOUNTPOINT) 161 162 # mount onedrive 163 systemctl --user daemon-reload 164 systemctl --user start $SERVICE_NAME 165 166 # automatically mount onedrive when you login 167 systemctl --user enable $SERVICE_NAME 168 169 # check onedriver's logs for the current day 170 journalctl --user -u $SERVICE_NAME --since today 171 ``` 172 173 ## Building onedriver yourself 174 175 In addition to the traditional [Go tooling](https://golang.org/dl/), you will 176 need a C compiler and development headers for `webkit2gtk-4.0` and `json-glib`. 177 On Fedora, these can be obtained with 178 `dnf install golang gcc pkg-config webkit2gtk3-devel json-glib-devel`. On 179 Ubuntu, these dependencies can be installed with 180 `apt install golang gcc pkg-config libwebkit2gtk-4.0-dev libjson-glib-dev`. 181 182 ```bash 183 # to build and run the binary 184 make 185 mkdir mount 186 ./onedriver mount/ 187 188 # in new window, check out the mounted filesystem 189 ls -l mount 190 191 # unmount the filesystem 192 fusermount3 -uz mount 193 # you can also just "ctrl-c" onedriver to unmount it 194 ``` 195 196 ### Running the tests 197 198 The tests will write and delete files/folders on your onedrive account at the 199 path `/onedriver_tests`. Note that the offline test suite requires `sudo` to 200 remove network access to simulate being offline. 201 202 ```bash 203 # setup test tooling for first time run 204 make test-init 205 206 # actually run tests 207 make test 208 ``` 209 210 ### Installation from source 211 212 onedriver has multiple installation methods depending on your needs. 213 214 ```bash 215 # install directly from source 216 make 217 sudo make install 218 219 # create an RPM for system-wide installation on RHEL/CentOS/Fedora using mock 220 sudo dnf install golang gcc webkit2gtk3-devel json-glib-devel pkg-config git \ 221 rsync rpmdevtools rpm-build mock 222 sudo usermod -aG mock $USER 223 newgrp mock 224 make rpm 225 226 # create a .deb for system-wide installation on Ubuntu/Debian using pbuilder 227 sudo apt update 228 sudo apt install golang gcc libwebkit2gtk-4.0-dev libjson-glib-dev pkg-config git \ 229 rsync devscripts debhelper build-essential pbuilder 230 sudo pbuilder create # may need to add "--distribution focal" on ubuntu 231 make deb 232 ``` 233 234 ## Troubleshooting 235 236 During your OneDrive travels, you might hit a bug that I haven't squashed yet. 237 Don't panic! In most cases, the filesystem will report what happened to whatever 238 program you're using. (As an example, an error mentioning a "read-only 239 filesystem" indicates that your computer is currently offline.) 240 241 If the filesystem appears to hang or "freeze" indefinitely, its possible the 242 fileystem has crashed. To resolve this, just restart the program by unmounting 243 and remounting things via the GUI or by running `fusermount3 -uz $MOUNTPOINT` on 244 the command-line. 245 246 If you really want to go back to a clean slate, onedriver can be completely 247 reset (delete all cached local data) by deleting mounts in the GUI or running 248 `onedriver -w`. 249 250 If you encounter a bug or have a feature request, open an issue in the "Issues" 251 tab here on GitHub. The two most informative things you can put in a bug report 252 are the logs from the bug/just before encountering the bug (get logs via 253 `journalctl --user -u $SERVICE_NAME --since today` ... see docs for correct 254 value of `$SERVICE_NAME`) and/or instructions on how to reproduce the issue. 255 Otherwise I have to guess what the problem is :disappointed: 256 257 ## Known issues & disclaimer 258 259 Many file browsers (like 260 [GNOME's Nautilus](https://gitlab.gnome.org/GNOME/nautilus/-/issues/1209)) will 261 attempt to automatically download all files within a directory in order to 262 create thumbnail images. This is somewhat annoying, but only needs to happen 263 once - after the initial thumbnail images have been created, thumbnails will 264 persist between filesystem restarts. 265 266 Microsoft does not support symbolic links (or anything remotely like them) on 267 OneDrive. Attempting to create symbolic links within the filesystem returns 268 ENOSYS (function not implemented) because the functionality hasn't been 269 implemented... by Microsoft. Similarly, Microsoft does not expose the OneDrive 270 Recycle Bin APIs - if you want to empty or restore the OneDrive Recycle Bin, you 271 must do so through the OneDrive web UI (onedriver uses the native system 272 trash/restore functionality independently of the OneDrive Recycle Bin). 273 274 onedriver loads files into memory when you access them. This makes things very 275 fast, but obviously doesn't work very well if you have very large files. Use a 276 sync client like [rclone](https://rclone.org/) if you need the ability to copy 277 multi-gigabyte files to OneDrive. 278 279 OneDrive is not a good place to backup files to. Use a tool like 280 [restic](https://restic.net/) or [borg](https://www.borgbackup.org/) if you're 281 looking for a reliable encrypted backup tool. I know some of you want to "back 282 up your files to OneDrive". Don't do it. Restic and Borg are better in every 283 possible way than any OneDrive client ever will be when it comes to creating 284 backups you can count on. 285 286 Finally, this project is still in active development and is provided AS IS. 287 There are no guarantees. It might kill your cat.