One of the nice things about Git is that it's inherently distributed.
It's built to share. Even if you're only sharing a repository with other
computers on your own network, Git brings transparency to the act of
getting files from a shared location. As interfaces go, Git is pretty
simple. It varies from user to user, but the common incantation when
sitting down to get some work done is just `git pull` or maybe the
slightly more complex `git pull && git checkout -b my-branch`. Still,
for some people the idea of *entering a command* into their computer at
all is confusing or bothersome. Computers are meant to make life easy,
and computers are good at repetitious tasks, and so there are yet easier
ways to share files with Git.
Sparkleshare
============
The [Sparkleshare](
http://www.sparkleshare.org/) project is a
cross-platform, open source, Dropbox-style file sharing application
based on Git. It automates all Git commands, triggering the add, commit,
push, and pull processes with the simple act of dragging-and-dropping a
file into a specially-designated `Sparkleshare` directory. Because it is
based on Git, you get fast, diff-based pushes and pulls, and you inherit
all the benefits of Git version control and back-end infrastructure
(like Git hooks). It can be entirely self-hosted, or you can use it with
Git hosting services like [Gitlab](
http://gitlab.com), Github,
Bitbucket, and others. Furthermore, because it's basically just a
front-end to Git, you can access your Sparkleshare files on devices that
may not have a Sparkleshare client but do have Git clients.
Just as you get all the benefits of Git, you also get all the usual Git
restrictions: it's impractical to use Sparkleshare to store hundreds of
photos and music and videos because Git is designed and optimized for
text. Git certainly has the capability to store large files, but it is
designed to track history, so once a file is added to it, it's nearly
impossible to completely remove it. This somewhat limits the usefulness
of Sparkleshare for some people, but it makes it ideal for many
workflows, including [calendaring with
Git](LINK_TO_MY_GIT_CALENDARING_ARTICLE).
Installing Sparkleshare
-----------------------
Sparkleshare is cross-platform, with installers for Windows and Mac
available from their [website](
http://sparkleshare.org). For Linux,
there's a Flatpak in your software installer, or you can otherwise run
these commands in a terminal:
$ sudo flatpak remote-add flathub
https://flathub.org/repo/flathub.flatpakrepo
$ sudo flatpak install flathub org.sparkleshare.SparkleShare
Creating a Git Repository
=========================
Sparkleshare isn't SaaS (Software-as-a-Service). You run Sparkleshare on
your computer as a way to communicate with a Git repository, so
Sparkleshare itself doesn't store your data. If you don't have a Git
repository you want to sync a folder with yet, then you must create one
before launching Sparkleshare. You have three options: hosted Git,
self-hosted Git, or self-hosted Sparkleshare.
**Git Hosting**
Sparkleshare can use any Git repository you can access for storage, so
if you have or create an account with Gitlab or any other hosting
service, it can become the back-end for your Sparkleshare. For this
example, I'll use the open source [Notabug.org](
http://notabug.org)
service. It's a Git hosting service like Github and Gitlab, but unique
enough to prove that Sparkleshare is as flexible as can be. Creating a
new repository differs from host to host depending on the user
interface, but all of the major ones follow the same general model.
First, locate a button to create a new project or repository and click
on it to begin. Then step through the repository creation process,
providing a name for your repository, privacy level (repositories often
default to being public), and whether or not to initialize the
repository with a README file. Whether you need a README or not, enable
an initial README file. Starting a repository with a file isn't strictly
necessary, but it forces the Git host to instantiate a `master` branch
in the repository, which helps ensure that front-end applications like
Sparkleshare have a branch to commit and push to. It's also useful for
you to see a file, even if it's an almost empty README file, to confirm
that you have connected.
Once your repository has been created, obtain the URL it uses for SSH
clones. You can get this URL the same way anyone gets any URL for a Git
project: navigate to the page of the repository and look for the clone
button or field.
This is the address Sparkleshare uses to reach your data, so make note
of it. Your Git repository is now configured.
**Self-hosted Git**
You can use Sparkleshare to access a Git repository on any computer you
have access to. No special setup is required, aside from a bare Git
repository. However, if you want to give access to your Git repository
to anyone else, then you should run a Git manager like
[Gitolite](
http://gitolite.org) or Sparkleshare's own Dazzle server to
help you manage SSH keys and accounts. At the very least, you should
create a user specific to Git so that users with access to your Git
repository don't also automatically gain access to the rest of your
server.
Log in to your server as the Git user (or yourself, if you're very good
at managing user and group permissions) and create a repository:
$ mkdir ~/sparkly.git
$ cd ~/sparkly.git
$ git init --bare .
Your Git repository is now configured.
**Dazzle**
Sparkleshare's developers provide a Git management system called Dazzle
to help you self-host Git repositories.
On your server, download the Dazzle application to some location in your
path:
$ curl
https://raw.githubusercontent.com/hbons/Dazzle/master/dazzle.sh \
--output ~/bin/dazzle
$ chmod +x ~/bin/dazzle
Dazzle sets up a user specific to Git and Sparkleshare, and also
implements access rights based on keys generated by the Sparkleshare
application. For now, just set up a project:
$ dazzle create sparkly
Your server is now configured as a Sparkleshare host.
Configuring Sparkleshare
========================
When you launch Sparkleshare for the first time, you are prompted to
configure what server you want Sparkleshare to use for storage. This
process may feel like a first-run setup wizard, but it's actually the
usual process for setting up a new shared location within Sparkleshare.
Unlike many shared drive applications, with Sparkleshare you can have
several locations configured all at once. The first shared location you
configure isn't any more significant than any shared location you may
set up later, and you're not signing up with Sparkleshare or any other
service. You're just pointing Sparkleshare at a Git repository so it
knows what to keep your first Sparkleshare folder in sync with.
On the first screen, identify yourself by any means you want to have on
record in the Git commits that Sparkleshare makes on your behalf. You
can use anything, even fake information that resolves to nothing. It's
purely for the commit messages, which you may never even see if you have
no interest in reviewing the Git back-end processes.
The next screen prompts you to choose your hosting type. If you are
using Gitlab, Github, Planio, or Bitbucket, then select the appropriate
one. For anything else, select `Own server`.
At the bottom of this screen, you must enter the SSH clone URL. If
you're self-hosting, then the address is something like
`ssh://
[email protected]` and the remote path is the absolute path to
the Git repository you created for this purpose.
Based on my self-hosted examples above, the address to my imaginary
server is `ssh://
[email protected]:22122` (the `:22122` indicates a
nonstandard SSH port) and the remote path is `/home/git/sparkly.git`.
If I use my Notabug.org account instead, the address from the example
above is `
[email protected]` and the path is `seth/sparkly.git`.
The first time Sparkleshare attempts to connect to host, it will fail
because you have not yet copied the Sparkleshare client ID (really an
SSH key specific to the Sparkleshare application) to the Git host. This
is expected, so don't cancel the process. Leave the Sparkleshare setup
window open and obtain the client ID from the Sparkleshare icon in your
system tray:
Copy the client ID to your clipboard so you can add it to your Git host.
**Adding you client ID to a hosted Git account**
Minor UI differences aside, adding an SSH key (which is all the client
ID actually is) is basically the same process on any hosting service. In
your Git host's web dashboard, navigate to your user settings and find
the SSH Key category. Click the Add New Key button (or similar) and
paste in the contents of your Sparkleshare client ID.
Save the key. If you want someone else, such as collaborators or family
members, to be able to access this same repository, they must provide
you with their Sparkleshare client ID so you can add it to your account.
**Adding you client ID to a self-hosted Git account**
A Sparkleshare client ID is just an SSH key, so copy and paste it into
your Git user's `~/.ssh/authorized_keys` file.
**Adding you client ID with Dazzle**
If you are using Dazzle to manage your Sparkleshare projects, add a
client ID with this command:
$ dazzle link
When Dazzle prompts you for the ID, paste in the client ID found in the
Sparkleshare menu.
Using Sparkleshare
==================
Once you've added your client ID to your Git host, click the Retry
button in the Sparkleshare window to finish setup. When it's finished
cloning your repository, you can close the Sparkleshare setup window,
and you'll find a new `Sparkleshare` folder in your home directory. If
you set up a Git repository with a hosting service and chose to include
a README or license file, then you can see those in your Sparkleshare
directory.
Otherwise, there are some hidden directories, which you can see by
revealing hidden directories in your file manager.
You use Sparkleshare the same way you use any directory on your
computer: you put files into it. Any time a file or directory is placed
into a Sparkleshare folder, it's copied, in the background, to your Git
repository.
Since Git is designed to remember *everything*, you may want to exclude
specific file types from ever being recorded. There are a few reasons to
manage excluded files. By defining files that are off limits for
Sparkleshare, you can avoid accidental copying of large files. You can
also design a scheme for yourself that enables you to store files that
logically belong together (MIDI files with their `.flac` exports, for
instance) in one directory, but manually backup the large files yourself
whilst letting Sparkleshare backup the text-based files.
If you can't see hidden files in your system's file manager, then reveal
them. Navigate to your Sparkleshare folder, and then to the directory
representing your repository, and locate a file called `.gitignore` and
open it in a text editor. You can enter file extensions or file names,
one per line, into `.gitignore` and any file matching what you list will
be, as the file name suggests, ignored.
Thumbs.db
$RECYCLE.BIN/
.DS_Store
._*
.fseventsd
.Spotlight-V100
.Trashes
.directory
.Trash-*
*.wav
*.ogg
*.flac
*.mp3
*.m4a
*.opus
*.jpg
*.png
*.mp4
*.mov
*.mkv
*.avi
*.pdf
*.djvu
*.epub
*.od{s,t}
*.cbz
You know the types of files you encounter most often, so concentrate on
the files most likely to sneak their way into your Sparkleshare
directory. If you want to exercise a little overkill, then you can find
good collections of `.gitignore` files on Notabug.org and also on the
Internet at large.
With those entries in your `.gitignore` file, you can place large files
that you probably don't want sent to your Git host in your Sparkleshare
directory, and Sparkleshare ignores them entirely. Of course, that means
it's up to you to make sure they get onto a backup, or distributed to
your Sparkleshare collaborators, through some other means.
Automation
==========
Automation is part of the silent agreement we have with computers: they
do the repetitious, boring stuff that we humans either aren't very good
at doing or aren't very good at remembering. Sparkleshare is a nice,
simple way to automate routine distribution of data. It isn't right for
every Git repository, by any means. It doesn't have an interface for
advanced Git functions, it doesn't have a pause button or a manual
override. And that's OK, because its scope is intentionally limited.
Sparkleshare does what Sparkleshare sets out to do, and it does it well,
and it's one Git repository you won't have to think about.
If you have a use for that kind of steady, invisible automation, give
Sparkleshare a try.
