# git-remote-dropbox [](https://github.com/anishathalye/git-remote-dropbox/actions?query=workflow%3ACI) [](https://pypi.org/pypi/git-remote-dropbox/)
git-remote-dropbox is a transparent bidirectional bridge between Git and
Dropbox. It lets you use a Dropbox folder or a shared folder as a Git remote!
---
This Git remote helper makes Dropbox act like a _true Git remote_. It maintains
_all guarantees_ that are provided by a traditional Git remote while using
Dropbox as a backing store. This means that it works correctly even when there
are multiple people operating on the repository at once, making it possible to
use a Dropbox shared folder as a Git remote for collaboration.
Once the helper is installed, using it is as simple as adding a remote like
`dropbox:///path/to/repo`.
To clone repositories in folders or shared folders mounted in your Dropbox, you
can run:
```bash
git clone "dropbox:///path/to/repo"
```
To add a remote to an existing local repository, you can run:
```bash
git remote add origin "dropbox:///path/to/repo"
```
The repository directory will be created automatically the first time you push.
After adding the remote, you can treat it just like a regular Git remote. The
Dropbox-backed remote supports all operations that regular remotes support, and
it provides identical guarantees in terms of atomicity even when there are
concurrent operations, even when using a shared folder.
## Setup
### Install git-remote-dropbox
1. Prerequisites:
1. `python` and matching `pip`
2. `git`
2. Install this package with `pip install git-remote-dropbox`. Use `which git-remote-dropbox` to make sure it's available via `$PATH`. If not, edit `$PATH` appropriately.
### Log in to Dropbox
Run `git dropbox login` and follow the instructions to authenticate with OAuth
and log in to your Dropbox account.
## Sharing
The above gives you a way to create a Git repository on Dropbox and use it from multiple machines that you own. In other words, it's a convenient way to share a remote with your laptop and your desktop.
If you want to share with other people, you should explicitly share (e.g. via the Dropbox website) the root folder of the repo with your collaborators. Then they should also install git-remote-dropbox and log in *with their own account*.
## Multiple Accounts
git-remote-dropbox supports using multiple Dropbox accounts. You can have named
accounts with `git dropbox login <username>`. **These usernames are unrelated
to your Dropbox login; you can choose whatever names you want to organize your
accounts, e.g. "work".**
You can tell git-remote-dropbox to use a particular account by setting the git
remote URL appropriately, specifying a username like:
`dropbox://username@/path/to/repo`.
## Repository Manager
In addition to the git remote helper, git-remote-dropbox comes with an
additional tool to manage your logins and repositories on Dropbox. This tool
can be invoked as `git dropbox`.
The tool supports the following commands:
- `git dropbox login [username]`: log in, either with the default account (no
need to specify a username in remote), or with an alias (for multi-account
support)
- `git dropbox logout [username]`: log out
- `git dropbox show-logins`: list logged-in accounts
- `git dropbox set-head <remote> <branch>`: set default branch on the remote
- `git dropbox version`: show version
## Notes
- Do not directly interact with Git repositories in your Dropbox folder -always
use git-remote-dropbox. If you're using the Dropbox client to sync files,
it's a good idea to use [selective
sync](https://help.dropbox.com/installs-integrations/sync-uploads/selective-sync-overview)
and disable syncing of the folder containing the repository to avoid any
unexpected conflicts, just in case.
- git-remote-dropbox does not use the Dropbox desktop client - it uses the API
directly. It does not require that the desktop client is installed.
- The remote helper does not support shallow cloning.
- Cloning a repository or fetching a lot of objects produces lots of loose
objects. To save space in the local repository, run `git gc --aggressive`.
- If the remote HEAD (default branch on the remote) is not set, after cloning a
repository from Dropbox, Git will not automatically check out a branch. To
check out a branch, run `git checkout <branch>`. To set the default branch on
the remote, use the [`git dropbox`](#repository-manager) command.
## FAQ
**Why shouldn't I keep my Git repository in Dropbox and let the client sync
it?**
There seem to be a lot of articles on the Internet recommending this as a good
workflow. However, this is *not a good idea*! The desktop client is not aware
of how Git manages it's on-disk format, so if there are concurrent changes or
delays in syncing, it's possible to have conflicts that result in a corrupted
Git repository. This may be uncommon with the way the timing works out in the
single user case, but it's still not safe!
**Why shouldn't I keep a bare Git repository in a Dropbox shared folder, use it
as a folder-based Git remote, and sync it with the desktop client?**
There seem to be some articles on the Internet suggesting that this is a good
idea. It's not. Using the desktop client to sync a bare Git repository is not
safe. Concurrent changes or delays in syncing can result in a corrupted Git
repository.
**How can I access / recover my repository from Dropbox without using the
git-remote-dropbox helper?**
Because git-remote-dropbox uses an on-disk format that's compatible with Git,
accessing your repository without using the helper is easy:
1. Download the repository data (a directory containing the `objects` and
`refs` directories) from Dropbox.
2. Make a new directory and initialize an empty Git repository in the
directory.
3. Overwrite `.git/refs` and `.git/objects` in your newly initialized
repository with the data downloaded from Dropbox (using a command like `rm
-rf .git/{refs,objects} && cp -r /path/to/data/{refs,objects} .git/`).
4. Check out a branch (using a command like `git checkout -f master`).
5. Optionally, run `git gc --aggressive` to save disk space in your local
repository.
**How do I use git-remote-dropbox from behind a proxy server?**
You can use git-remote-dropbox from behind a proxy server by setting the
`HTTP_PROXY` and `HTTPS_PROXY` environment variables. See
[here](http://docs.python-requests.org/en/latest/user/advanced/#proxies) for
more details.
**How do I use git-remote-dropbox with submodules?**
You can allow this by setting
[`protocol.dropbox.allow`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-protocolltnamegtallow)
to `always`:
```bash
git config --global --add protocol.dropbox.allow always
```
## Design
To read about the design of git-remote-dropbox, see [DESIGN.md](DESIGN.md).
This could be especially useful if you're thinking about contributing to the
project.
## Contributing
Do you have ideas on how to improve git-remote-dropbox? Have a feature request,
bug report, or patch? Great! See [CONTRIBUTING.md](CONTRIBUTING.md) for
information on what you can do about that.
## License
Copyright (c) Anish Athalye. Released under the MIT License. See
[LICENSE.md](LICENSE.md) for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/anishathalye/git-remote-dropbox",
"name": "git-remote-dropbox",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "git dropbox",
"author": "Anish Athalye",
"author_email": "me@anishathalye.com",
"download_url": "https://files.pythonhosted.org/packages/01/1b/d799cd18327b6dc9bb66df6705320ffe7aa1284fc4573c9cf1b3527eb607/git-remote-dropbox-2.0.2.tar.gz",
"platform": null,
"description": "# git-remote-dropbox [](https://github.com/anishathalye/git-remote-dropbox/actions?query=workflow%3ACI) [](https://pypi.org/pypi/git-remote-dropbox/)\n\ngit-remote-dropbox is a transparent bidirectional bridge between Git and\nDropbox. It lets you use a Dropbox folder or a shared folder as a Git remote!\n\n---\n\nThis Git remote helper makes Dropbox act like a _true Git remote_. It maintains\n_all guarantees_ that are provided by a traditional Git remote while using\nDropbox as a backing store. This means that it works correctly even when there\nare multiple people operating on the repository at once, making it possible to\nuse a Dropbox shared folder as a Git remote for collaboration.\n\nOnce the helper is installed, using it is as simple as adding a remote like\n`dropbox:///path/to/repo`.\n\nTo clone repositories in folders or shared folders mounted in your Dropbox, you\ncan run:\n\n```bash\ngit clone \"dropbox:///path/to/repo\"\n```\n\nTo add a remote to an existing local repository, you can run:\n\n```bash\ngit remote add origin \"dropbox:///path/to/repo\"\n```\n\nThe repository directory will be created automatically the first time you push.\n\nAfter adding the remote, you can treat it just like a regular Git remote. The\nDropbox-backed remote supports all operations that regular remotes support, and\nit provides identical guarantees in terms of atomicity even when there are\nconcurrent operations, even when using a shared folder.\n\n## Setup\n\n### Install git-remote-dropbox\n\n1. Prerequisites:\n 1. `python` and matching `pip`\n 2. `git`\n2. Install this package with `pip install git-remote-dropbox`. Use `which git-remote-dropbox` to make sure it's available via `$PATH`. If not, edit `$PATH` appropriately.\n\n### Log in to Dropbox\n\nRun `git dropbox login` and follow the instructions to authenticate with OAuth\nand log in to your Dropbox account.\n\n## Sharing\n\nThe above gives you a way to create a Git repository on Dropbox and use it from multiple machines that you own. In other words, it's a convenient way to share a remote with your laptop and your desktop.\n\nIf you want to share with other people, you should explicitly share (e.g. via the Dropbox website) the root folder of the repo with your collaborators. Then they should also install git-remote-dropbox and log in *with their own account*.\n\n## Multiple Accounts\n\ngit-remote-dropbox supports using multiple Dropbox accounts. You can have named\naccounts with `git dropbox login <username>`. **These usernames are unrelated\nto your Dropbox login; you can choose whatever names you want to organize your\naccounts, e.g. \"work\".**\n\nYou can tell git-remote-dropbox to use a particular account by setting the git\nremote URL appropriately, specifying a username like:\n`dropbox://username@/path/to/repo`.\n\n## Repository Manager\n\nIn addition to the git remote helper, git-remote-dropbox comes with an\nadditional tool to manage your logins and repositories on Dropbox. This tool\ncan be invoked as `git dropbox`.\n\nThe tool supports the following commands:\n\n- `git dropbox login [username]`: log in, either with the default account (no\n need to specify a username in remote), or with an alias (for multi-account\n support)\n- `git dropbox logout [username]`: log out\n- `git dropbox show-logins`: list logged-in accounts\n- `git dropbox set-head <remote> <branch>`: set default branch on the remote\n- `git dropbox version`: show version\n\n## Notes\n\n- Do not directly interact with Git repositories in your Dropbox folder -always\n use git-remote-dropbox. If you're using the Dropbox client to sync files,\n it's a good idea to use [selective\n sync](https://help.dropbox.com/installs-integrations/sync-uploads/selective-sync-overview)\n and disable syncing of the folder containing the repository to avoid any\n unexpected conflicts, just in case.\n\n- git-remote-dropbox does not use the Dropbox desktop client - it uses the API\n directly. It does not require that the desktop client is installed.\n\n- The remote helper does not support shallow cloning.\n\n- Cloning a repository or fetching a lot of objects produces lots of loose\n objects. To save space in the local repository, run `git gc --aggressive`.\n\n- If the remote HEAD (default branch on the remote) is not set, after cloning a\n repository from Dropbox, Git will not automatically check out a branch. To\n check out a branch, run `git checkout <branch>`. To set the default branch on\n the remote, use the [`git dropbox`](#repository-manager) command.\n\n## FAQ\n\n**Why shouldn't I keep my Git repository in Dropbox and let the client sync\nit?**\n\nThere seem to be a lot of articles on the Internet recommending this as a good\nworkflow. However, this is *not a good idea*! The desktop client is not aware\nof how Git manages it's on-disk format, so if there are concurrent changes or\ndelays in syncing, it's possible to have conflicts that result in a corrupted\nGit repository. This may be uncommon with the way the timing works out in the\nsingle user case, but it's still not safe!\n\n**Why shouldn't I keep a bare Git repository in a Dropbox shared folder, use it\nas a folder-based Git remote, and sync it with the desktop client?**\n\nThere seem to be some articles on the Internet suggesting that this is a good\nidea. It's not. Using the desktop client to sync a bare Git repository is not\nsafe. Concurrent changes or delays in syncing can result in a corrupted Git\nrepository.\n\n**How can I access / recover my repository from Dropbox without using the\ngit-remote-dropbox helper?**\n\nBecause git-remote-dropbox uses an on-disk format that's compatible with Git,\naccessing your repository without using the helper is easy:\n\n1. Download the repository data (a directory containing the `objects` and\n `refs` directories) from Dropbox.\n2. Make a new directory and initialize an empty Git repository in the\n directory.\n3. Overwrite `.git/refs` and `.git/objects` in your newly initialized\n repository with the data downloaded from Dropbox (using a command like `rm\n -rf .git/{refs,objects} && cp -r /path/to/data/{refs,objects} .git/`).\n4. Check out a branch (using a command like `git checkout -f master`).\n5. Optionally, run `git gc --aggressive` to save disk space in your local\n repository.\n\n**How do I use git-remote-dropbox from behind a proxy server?**\n\nYou can use git-remote-dropbox from behind a proxy server by setting the\n`HTTP_PROXY` and `HTTPS_PROXY` environment variables. See\n[here](http://docs.python-requests.org/en/latest/user/advanced/#proxies) for\nmore details.\n\n**How do I use git-remote-dropbox with submodules?**\n\nYou can allow this by setting\n[`protocol.dropbox.allow`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-protocolltnamegtallow)\nto `always`:\n\n```bash\ngit config --global --add protocol.dropbox.allow always\n```\n\n## Design\n\nTo read about the design of git-remote-dropbox, see [DESIGN.md](DESIGN.md).\nThis could be especially useful if you're thinking about contributing to the\nproject.\n\n## Contributing\n\nDo you have ideas on how to improve git-remote-dropbox? Have a feature request,\nbug report, or patch? Great! See [CONTRIBUTING.md](CONTRIBUTING.md) for\ninformation on what you can do about that.\n\n## License\n\nCopyright (c) Anish Athalye. Released under the MIT License. See\n[LICENSE.md](LICENSE.md) for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A transparent bidirectional bridge between Git and Dropbox",
"version": "2.0.2",
"project_urls": {
"Homepage": "https://github.com/anishathalye/git-remote-dropbox"
},
"split_keywords": [
"git",
"dropbox"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d658fc41ab62d26eacd0e1bf01d1de433dd7e1f67b0e0f1755e5d4f589f70539",
"md5": "ebd19a85210db6ad82bb9dbcfaa2ff8f",
"sha256": "abdcf986acf8b08f24ec2c0f70ebf23c1dcdf964a6390be54a1147ee884a4eda"
},
"downloads": -1,
"filename": "git_remote_dropbox-2.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ebd19a85210db6ad82bb9dbcfaa2ff8f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 20477,
"upload_time": "2024-03-15T10:23:01",
"upload_time_iso_8601": "2024-03-15T10:23:01.544233Z",
"url": "https://files.pythonhosted.org/packages/d6/58/fc41ab62d26eacd0e1bf01d1de433dd7e1f67b0e0f1755e5d4f589f70539/git_remote_dropbox-2.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "011bd799cd18327b6dc9bb66df6705320ffe7aa1284fc4573c9cf1b3527eb607",
"md5": "e450dd3ae66ed6ddd46486888edc8f54",
"sha256": "a1619097e97aca18835bfdde826ffc915fcecff7cfd0e5dad716bdfd26024bb1"
},
"downloads": -1,
"filename": "git-remote-dropbox-2.0.2.tar.gz",
"has_sig": false,
"md5_digest": "e450dd3ae66ed6ddd46486888edc8f54",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 20671,
"upload_time": "2024-03-15T10:23:05",
"upload_time_iso_8601": "2024-03-15T10:23:05.250479Z",
"url": "https://files.pythonhosted.org/packages/01/1b/d799cd18327b6dc9bb66df6705320ffe7aa1284fc4573c9cf1b3527eb607/git-remote-dropbox-2.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-15 10:23:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "anishathalye",
"github_project": "git-remote-dropbox",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "git-remote-dropbox"
}
JSON
