git.cworth.org Git - nogit/blob - README

   1 nogit: Using git to track files without the user using git
   2
   3 Summary
   4 =======
   5 Let's see, nogit is a very simple tool that uses git under the hood to
   6 allow for collaboration on files, but without requiring the the
   7 collaborators to invoke git commands. Any time a user might invoke
   8 "git commit", or "git push", or "git pull", etc. the user instead just
   9 invokes "nogit sync". And the user will not be prompted to fill out a
  10 commit message or to resolve conflicts, etc.
  11
  12 This is not intended as an alternative to git. If you're already using
  13 git, please continue to do so, (creating clean code history with
  14 detailed commit messages, etc.). Instead, nogit is intended for text
  15 files that you otherwise wouldn't have even put into git. And
  16 specifically, it's only suitable for text files where a naive "union
  17 merge" is the right thing. To be precise, a nogit merge will always
  18 silently give you "both sides" of any merge conflict, and will not
  19 provide any conflict markers, (it won't even indicate that any
  20 conflict happened). It also won't give any predictable behavior on the
  21 ordering of lines in cases like this. So if your data isn't safe
  22 against that kind of corruption, then you'll probably not want to use
  23 it with nogit.
  24
  25 The original data for which nogit was invented for was a simple TODO
  26 list where different people were adding items they wanted to work on,
  27 then removing them when they completed them. These people wanted to
  28 keep each other informed about their activities, so they wanted to
  29 share items in a single file. But there was no functional significance
  30 to the order of items. Finally, it was unlikely that two people would
  31 edit any one item in two different ways, (and even if they did it
  32 would be trivial and painless to sort this out after the fact).
  33
  34 Installation
  35 ============
  36 The nogit implementation is a simple bash script named "nogit". To
  37 install it, simply copy it to a directory on your PATH. Or, if you'd
  38 like to be able to follow along with nogit changes from a git
  39 repository, you might create a symlink from a directory on your PATH
  40 to the nogit script in the git repostiory.
  41
  42 Usage
  43 =====
  44 Presumably, you've been pointed to a repository which is intended to
  45 be used with nogit. These repositories are often paired with a
  46 "parent" repository that is being tracked with git. If so, the
  47 procedure for cloning should look something like this:
  48
  49         git clone /url/of/parent
  50         cd parent
  51         nogit clone /url/of/nogit/child
  52
  53 And after that, you can run "nogit sync" whenever convenient, (when
  54 you've made changes or you think there might be upstream changes to
  55 the files being tracked in the nogit repository). Note that "nogit
  56 sync" should not ever ask for user input, so it's appropriate to call
  57 "nogit sync" from an autoamted system, (such as a text editor's hook
  58 when saving a file).
  59
  60 Integration with emacs
  61 ======================
  62 If you're an emacs user, here is some code you could put into your
  63 .emacs file to have "nogit sync" called automatically for you for any
  64 nogit-controlled files whenever you open one, begin editing it, or
  65 save it:
  66
  67   ; Run "nogit sync" if there is a .noggit directory here.
  68   ;
  69   ; Note: There is an important protection built into this implementation:
  70   ;
  71   ;       We bind 'in-nogit-sync and test whether it's bound to avoid
  72   ;       infinite recursion. This could otherwise come about because
  73   ;       the revert-buffer function could trigger the find-file-hook
  74   ;       and recurse.
  75   (defun nogit-sync-if-configured ()
  76     (interactive)
  77     (if (and
  78         (buffer-file-name)
  79          (file-exists-p (format "%s/../.nogit" (buffer-file-name)))
  80          (not (boundp 'in-nogit-sync))
  81          )
  82         (let ((in-nogit-sync t))
  83           (message (substring (shell-command-to-string "nogit sync") 0 -1))
  84           (revert-buffer nil t)
  85         )
  86       )
  87     )
  88
  89   ; Arrange to run "nogit sync" when the user loads a nogit-controlled file,
  90   ; starts editing it for the first time, or saves it.
  91   (add-hook 'find-file-hook 'nogit-sync-if-configured)
  92   (add-hook 'first-change-hook 'nogit-sync-if-configured)
  93   (add-hook 'after-save-hook 'nogit-sync-if-configured)
  94
  95 Preparing git repositories for use with nogit
  96 =============================================
  97 If you're interested in setting up a parent and child repository for
  98 use with nogit, here's what you'll want to do:
  99
 100     In the parent repository
 101     ------------------------
 102     Add the following to .gitignore:
 103        .nogit
 104        .gitattributes
 105        Any files to be tracked in the child nogit repository
 106
 107     For the child repository
 108     ------------------------
 109     Create a new git repository
 110     Add the files to be tracked via nogit
 111     Add a .gitattributes file with contents such as:
 112
 113         * merge=union
 114
 115     The * is a pattern to match the files you're tracking. You don't
 116     necessarily need to use '*' you can explicitly name the files of
 117     interest. But the important thing is that all files tracked by
 118     nogit use the "union" merge driver (so that merges don't result in
 119     conflicts requiring user intervention).
 120
 121 Motivation
 122 ==========
 123 I originally came up with nogit when I started maintaining a simple
 124 TODO file for a project which had a code implementation split across
 125 multiple code repositories. I was intentionally keeping my TODO file
 126 outside of revision control to be lightweight in a couple of ways:
 127
 128   1. Many TODO items required implementing a feature in multiple
 129      repositories (both client and server, say), so having a separate
 130      TODO file meant I didn't need to decide which repository to add
 131      the TODO file to. And I also didn't need to add the same entriy
 132      to TODO files in each of multiple repositories.
 133
 134   2. TODO items are self-descriptive. Any commit message I might have
 135      written when adding a TODO item would be adequate as "Add <item>"
 136      and similarly for "Remove <item>" so there's inherently no
 137      advantage to commit messages for these changes.
 138
 139 Of course, a significant disadvantage of my approach was that my TODO
 140 file was totally private. I was missing out on the collaborative
 141 features that git provides.
 142
 143 So, nogit was conceived of as a way to keep my lightweight process of
 144 maintaining the TODO file, (simply editing the file and doing nothing
 145 more), while also allowing for distributed editing of the file.