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 Installation
  13 ============
  14 The nogit implementation is a simple bash script named "nogit". To
  15 install it, simply copy it to a directory on your PATH. Or, if you'd
  16 like to be able to follow along with nogit changes from a git
  17 repository, you might create a symlink from a directory on your PATH
  18 to the nogit script in the git repostiory.
  19
  20 Usage
  21 =====
  22 Presumably, you've been pointed to a repository which is intended to
  23 be used with nogit. These repositories are often paired with a
  24 "parent" repository that is being tracked with git. If so, the
  25 procedure for cloning should look something like this:
  26
  27         git clone /url/of/parent
  28         cd parent
  29         nogit clone /url/of/nogit/child
  30
  31 And after that, you can run "nogit sync" whenever convenient, (when
  32 you've made changes or you think there might be upstream changes to
  33 the files being tracked in the nogit repository). Note that "nogit
  34 sync" should not ever ask for user input, so it's appropriate to call
  35 "nogit sync" from an autoamted system, (such as a text editor's hook
  36 when saving a file).
  37
  38 Integration with emacs
  39 ======================
  40 If you're an emacs user, here is some code you could put into your
  41 .emacs file to have "nogit sync" called automatically for you for any
  42 nogit-controlled files whenever you open one, begin editing it, or
  43 save it:
  44
  45   ; Run "nogit sync" if there is a .noggit directory here.
  46   ;
  47   ; Note: There is an important protection built into this implementation:
  48   ;
  49   ;       We bind 'in-nogit-sync and test whether it's bound to avoid
  50   ;       infinite recursion. This could otherwise come about because
  51   ;       the revert-buffer function could trigger the find-file-hook
  52   ;       and recurse.
  53   (defun nogit-sync-if-configured ()
  54     (interactive)
  55     (if (and
  56         (buffer-file-name)
  57          (file-exists-p (format "%s/../.nogit" (buffer-file-name)))
  58          (not (boundp 'in-nogit-sync))
  59          )
  60         (let ((in-nogit-sync t))
  61           (message (substring (shell-command-to-string "nogit sync") 0 -1))
  62           (revert-buffer nil t)
  63         )
  64       )
  65     )
  66
  67   ; Arrange to run "nogit sync" when the user loads a nogit-controlled file,
  68   ; starts editing it for the first time, or saves it.
  69   (add-hook 'find-file-hook 'nogit-sync-if-configured)
  70   (add-hook 'first-change-hook 'nogit-sync-if-configured)
  71   (add-hook 'after-save-hook 'nogit-sync-if-configured)
  72
  73 Preparing git repositories for use with nogit
  74 =============================================
  75 If you're interested in setting up a parent and child repository for
  76 use with nogit, here's what you'll want to do:
  77
  78     In the parent repository
  79     ------------------------
  80     Add the following to .gitignore:
  81        .nogit
  82        .gitattributes
  83        Any files to be tracked in the child nogit repository
  84
  85     For the child repository
  86     ------------------------
  87     Create a new git repository
  88     Add the files to be tracked via nogit
  89     Add a .gitattributes file with contents such as:
  90
  91         * merge=union
  92
  93     The * is a pattern to match the files you're tracking. You don't
  94     necessarily need to use '*' you can explicitly name the files of
  95     interest. But the important thing is that all files tracked by
  96     nogit use the "union" merge driver (so that merges don't result in
  97     conflicts requiring user intervention).
  98
  99 Motivation
 100 ==========
 101 I originally came up with nogit when I started maintaining a simple
 102 TODO file for a project which had a code implementation split across
 103 multiple code repositories. I was intentionally keeping my TODO file
 104 outside of revision control to be lightweight in a couple of ways:
 105
 106   1. Many TODO items required implementing a feature in multiple
 107      repositories (both client and server, say), so having a separate
 108      TODO file meant I didn't need to decide which repository to add
 109      the TODO file to. And I also didn't need to add the same entriy
 110      to TODO files in each of multiple repositories.
 111
 112   2. TODO items are self-descriptive. Any commit message I might have
 113      written when adding a TODO item would be adequate as "Add <item>"
 114      and similarly for "Remove <item>" so there's inherently no
 115      advantage to commit messages for these changes.
 116
 117 Of course, a significant disadvantage of my approach was that my TODO
 118 file was totally private. I was missing out on the collaborative
 119 features that git provides.
 120
 121 So, nogit was conceived of as a way to keep my lightweight process of
 122 maintaining the TODO file, (simply editing the file and doing nothing
 123 more), while also allowing for distributed editing of the file.