Collaborate and track tasks with ease using GitDocs

At Miso, we have tried a lot of task tracking tools of all shapes and sizes. However, since we are a small team, we all end up using those in conjunction with just a plain text file where we ‘really’ track our tasks. Nothing beats a simple text file for detailed personal task tracking and project tracking. I have been using text-file based task management since as long as I can remember and most of the team shares this sentiment. A separate issue that commonly comes up is just a place to dump code snippets, setup guides, team references, etc. We have used a wiki for this, and are currently using the Github wiki for this very purpose. A third common need is a place to dump software, images, mocks, etc and we currently use dropbox for this along with a shared network drive.

Recently, a discussion arose around the possibility of just using a simple git repository of our own to serve all these disparate purposes. Namely, we needed a place to do personal and project task tracking, store useful shared code snippets, and dump random files, notes, etc that the development team needs access to. Fundamentally, what prevents a simple git repository shared between all developers serve this task? Well, there are a few obstacles to this purely git based approach.

The first is that with shared files and docs, you don’t want to have to worry about constantly pushing and pulling. Changes are happening all the time, text is being changed or files are being added and having to manually commit every line change to a text file doesn’t really make sense for this use case. We really wanted something like Dropbox…namely when a file is changed, the updates are pushed and pulled automatically. Second, we really need a way to view files in the browser. Imagine writing a great markdown guide and never being able to see the guide rendered in proper markdown. We needed a way for this shared repository to be browsable in the browser.

So after discussing this, we decided to build our ‘ideal’ solution and the result is gitdocs, a way to collaborate on documents and files effortlessly using just git and the file system. Think of gitdocs as a combination of dropbox and google docs but free and open-source.


Install the gem:

gem install gitdocs

If you have Growl installed, you’ll probably want to run brew install growlnotify to enable Growl support.


Gitdocs is a rather simple library with only a few basic commands. You need to be able to add paths for gitdocs to monitor, start/stop gitdocs and be able to check the status. First, you need to add the doc folders to watch:

gitdocs add my/path/to/watch

You can remove and clear paths as well:

gitdocs rm my/path/to/watch
gitdocs clear

Then, you need to startup gitdocs:

gitdocs start

You can also stop and restart gitdocs as needed. Run

gitdocs status

for a helpful listing of the current state. Once gitdocs is started, simply start editing or adding files to your designated git repository. Changes will be automatically pushed and pulled to your local repo.

You can also have gitdocs fetch a remote repository with:

gitdocs create my/path/for/doc

This will clone the repo and add the path to your watched docs. Be sure to restart gitdocs to have path changes update:

gitdocs restart

To view the docs in your browser with file formatting:

gitdocs serve

and then visit http://localhost:8888 for access to all your docs in the browser.


Our development team has started using Gitdocs extensively for all types of files and documents. Primarily, task tracking, file sharing, note taking, code snippets, etc. All of this in git repos, automatically managed by gitdocs and viewable in your favorite text editor or browser. Be sure to check out the gitdocs repository for more information.

30 thoughts on “Collaborate and track tasks with ease using GitDocs”

  1. Very important part of Dropbox-like functionality is the encryption of all the content… I guess it could be done with git post-commit hooks, have you thought of adding it?

    • The Dropbox encryption is useless. You don’t have your own private key (since that’s how they deduplicate on their servers).

  2. How do you manage conflicts ? Even if the sync is fast it may still happen if one of the computers gets offline.

    @ivan: Dropbox is only encrypted on the transport side, like git. All your files are visible by Dropbox employees.

    • Yes, we are in the process of managing git conflicts similar to the approach dropbox takes. The functionality is already in master and being tested to properly handle conflicts by keeping all 3 versions of the file (original, yours, theirs).

  3. I am trying to use my own git repository on an SSH server but am running into errors. Is there something that needs to be done other than running ‘git init –bare’ on the remote repo?

    • Can you update to gitdocs 0.3.1 and then run ‘gitdocs stop && gitdocs start -D’ and give us the output. You shouldn’t have to do anything other then ‘git init –bare’

      • When I run ‘gitdocs start -D’ I am prompted with this:

        Running in debug mode
        Gitdocs v0.2.0
        Using configuration root: '/Users/jonathan/.gitdocs'
        Watch paths: /Users/jonathan/Desktop/gitdocs
        Running gitdocs!: Running gitdocs in `/Users/jonathan/Desktop/gitdocs'
        root@'s password: Watch threads: Thread status: 'sleep', running: true
        Joined 1 watch threads...running
        >> Thin web server (v1.3.1 codename Triple Espresso)
        >> Maximum connections set to 1024
        >> Listening on, CTRL+C to stop

        when I enter the password, I receive this error:

        There was a problem synchronizing this gitdoc: A problem occurred in /Users/jonathan/Desktop/gitdocs:
        Fetching origin
        fatal: origin/master - not something we can merge

      • My apologies, I just noticed that my gitdocs version is out of date. I installed using gem and this is what installed. I am working to update now.

      • Okay, I updated to 0.3.1 and I am experiencing the same issues. After being prompted for a password I receive the following error:

        There was a problem synchronizing this gitdoc: A problem occurred in /Users/jonathan/Desktop/gitdocs:
        Fetching origin
        fatal: origin/master - not something we can merge

        • Minimally, you need to be able to perform a “git pull origin master” in your share. It sounds like that is failing. You should probably go to your share on your terminal, and see that you can push and pull from it.

    • Looks like the issue has been resolved. I was starting with an empty repo on both the server and the client. Once I did a commit on the client and pushed the master it stopped complaining.

  4. Hi,

    i would love to try this, but after adding onefile, regardless on Webinterface or local, gitdocs just crashes without any information:

    [code]Starting in debug mode
    Gitdocs v0.4.3
    Using configuration root: ‘/home/tetja/.gitdocs’
    Shares: #<Gitdocs::Configuration::Share id: 1, path: "/home/tetja/repos/gitdoc", polling_interval: 15.0, notification: true, remote_name: "origin", branch_name: "master">
    Please install libnotify gem for Linux notification support and add it to your Gemfile
    Warning: untrusted X11 forwarding setup failed: xauth key data not generated
    Warning: No xauth data; using fake authentication data for X11 forwarding.
    >> Thin web server (v1.3.1 codename Triple Espresso)
    >> Maximum connections set to 1024
    >> Listening on, CTRL+C to stop
    file: invalid option — ‘I’
    Usage: file [-bchikLlNnprsvz0] [–apple] [–mime-encoding] [–mime-type]
    [-e testname] [-F separator] [-f namefile] [-m magicfiles] file …
    file -C [-m magicfiles]
    file [–help]

  5. Well. Where’s the point of sharing from computer A with computer B? If u just version control on ur own machine, it’s not really dropbox, more like autogit.

    • If any number of computers connect to the share, then all computers have access to the same files. Also, you can easily setup a share on a server that is remotely accessible and access the web front-end and/or files from there very similar to hosted dropbox. A little confused on what you were expecting.

      • No problem. My English is not so great.
        I mean that:
        There is computer A with gitdocs on it. And there is computer B with gitdocs on it. I don’t understand how I can make sure, that all tracked files from A are automatically stored on B in the most up to date version.
        What do u mean with “connect to the share”? What is a share and how to connect to it?

        • A share is just a monitored gitdocs path. So in your case, you would setup or get a git repo designated as to be used as a ‘share’ and then on each computer you would do:

          $ gem install gitdocs
          $ gitdocs create /local/path/for/share git://path/to/git/repo.git
          $ gitdocs start

          This will install gitdocs and then download the git repo into the specified local path. If you do this on each machine, then all changes will be automatically pushed and pulled for both computer A and B when files are modified in the share.

  6. Just wondering if gitdocs tracks every changes forever…
    Tracking every changes forever will raise disk concerns if using this with some big binary data like PSD or movies etc…
    Dropbox has limitation for every file history. Does gitdocs handle this concerns?

    Sorry for my bad English.

    • Large binaries do become a problem for storage and efficiency of git. We have plans to solve this but have not implemented them yet. So as of right now, I would minimize the amount of huge binary files stored in gitdocs.

      At Miso, our team actually uses gitdocs in conjunction with Dropbox. We find Dropbox is ideal for galleries, videos, and large binary files of all sorts. We use gitdocs for storing our actual “docs”: Task lists, wiki pages, planning docs, collaborative designs, notes, guides, code snippets, etc.

      You will find that the gitdocs browser front-end is well suited for this usage scenario since you can browse formatted wiki pages, view files with smart syntax highlighting, edit files with a rich text editor, search all your files, as well as view individual file revision histories.

Comments are closed.