Skip to content

Latest commit

 

History

History
108 lines (71 loc) · 6.62 KB

README.md

File metadata and controls

108 lines (71 loc) · 6.62 KB
Raw

syncdocs

Syncdocs version nocke syncdocs tests

highly simplified git versioning for non-technical users.
“surviving your daily flood of bureaucratic cruft”

SyncDocs Cover Image

Is syncdocs a good tool to work on my source code?

No, isn't. Use regular git, to have defined precisely version states for every file of your repository for every commit you do. Nothing of value for you here.

I need to jam my letters, invoices, tax stuff, etc… together in one place, well in several places, but basically the same huge tree. I want mutual updating and not loosing elder versions of stuff. Should be extremly easy to do that syncing.

This is a tool, that helps handling those incoming, ever-growing documents (i.e. invoices, notes, pdfs, bureaucractic cruft) in one central place, yet also decentralized, with offline access and syncing as a nobrainer.

syncdocs has 1 end-user friendly command with 0 parameters to use. As much as I love git, no commit|pull|push|rebase and certainly no resolve-merge-conflicts makes things much easier for end users. Yet, it does harnesses many benefits of regular git use:

  • very easy syncing

  • versioning of course

  • largely conflict-free merges

  • rename detection (quite a feature actually!)

  • smart merging of anything plain-text (something-added-here vs. something-added-there in the same file will go together as you may expect)

  • some opinionated-ness, when non-text file changes collide (PDFs, images, …). spoiler: both versions will make it into recoverably version history)

  • recoverability (it doesn't matter if your server or client get's stolen or destroyed, as long as the-other-side is still around)

  • no system/platform/vendor-lock (all files are still in plain sight, in your file system, in a valid git repository, no fragile database, not somewhere in the cloud, …) If you do get into trouble, at least a git-savy person should be able to help.

    syncdocs TBD ▁

technical view

The idea being to sync personal data (text, pdf documents and invoices, screenshots, not source code) between a central git repository and various workstations with regular client repos

The idea being that your family members can also add stuff offline, i.e. on the road, and it all eventually ends up everywhere...

Sounds like something git would do out of the box, right? Yeah, but...

  • central repo is editable, too, not a pure-server “bare repo”
  • end-users get a single, zero-param syncdocs command, no pull, no add, no commit, no push, never to bother with merge conflicts
  • collisions in given usage scenarios shall be rare (it's mostly about adding cruft), but will occur: in which case both versions are preserved in version history: the more central one “wins” as the latter version, the other one preserved underneath.
  • it's still valid git repos on all ends (→no vendor-lock/platform neutrality), so you can add/integrate further things (i.e. commit hooks to the server), or analyse/retrieve elder versions with regular git tools like my favourite, smartgit.

author

Frank Nocke

development

This initially developed as a shell script, but things got a bit more tricky on some edge cases, so robust testing definelty required. Sso this deserved a second look, proper package, proper testing to ensure integrity and reliabilty around a number of edge cases, primarily as most git users would guess: merging.

The plan is to deliver as an npm package, so it truly becomes yet-another command (w/o path fiddling).

requirements

Presence of a sufficient node (≥v20) and git version (≥v2.2) is expected to be present (syncdocs doesn't install neither) and checked on (every) script run.

getting started

tbd

  • getting package
  • install/check node / git version
  • mounting/samba
  • default/user conf

configuration

The “topology” here is very simply a „star“ with 1 central SHARE repo (in which you may indeed work, too!) and an arbitrary number of LOCAL repos. Where that “arbitrary” number might very well be 1, if you happen to have one desktop for home (as SHARE) and 1 laptop on the go. It's easy to later on add additional members.

your SHARE repo (in 1 single place, i.e. storage media on your NAS) needs to provide a .syncshare.jsonfile with global settings relating to your entire system

→ if you are happy with the default settings, e.g. for excludedExtensions, MAX_FILE_SIZE_MB, it's sheer presence is enough (with or without empty curly brackets inside). Then it's just a marker file.

{
  "excludedExtensions": [... ,
  "MAX_FILE_SIZE_MB": 30,
}

your LOCAL repo (on every one of your machines) however does need to provide a .synclocal.json file with EXACTLY these 2 entries:

{
    machineName: os.hostname(), // what uname -n delivers, localRepo: '/home/user/'
    localRepo: 'mySyncDocsFolder', // again, ensuring the right  place
    shareRepo: '/fritzbox/usb-stick/SHARE' // the share repo to connect to
}

End of line comments with //, so called JSONC, are okay. Also “trailing commas” are no problem.

...

disclaimer

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.