X-Git-Url: https://git.cworth.org/git?p=nogit;a=blobdiff_plain;f=README;h=bae558f7e2e9283bf55694e1578fceadbf227c99;hp=fcf7d32ae95ddf8855e64d1d06d1c3998500aa92;hb=HEAD;hpb=6c2268e15b68765e5e5c093ee7dc293fc1be9f66

diff --git a/README b/README
index fcf7d32..bae558f 100644
--- a/README
+++ b/README
@@ -3,12 +3,34 @@ nogit: Using git to track files without the user using git
 Summary
 =======
 Let's see, nogit is a very simple tool that uses git under the hood to
-allow for collaboration on files, but without requiring the the
+allow for collaboration on files, but without requiring the
 collaborators to invoke git commands. Any time a user might invoke
 "git commit", or "git push", or "git pull", etc. the user instead just
 invokes "nogit sync". And the user will not be prompted to fill out a
 commit message or to resolve conflicts, etc.
 
+This is not intended as an alternative to git. If you're already using
+git, please continue to do so, (creating clean code history with
+detailed commit messages, etc.). Instead, nogit is intended for text
+files that you otherwise wouldn't have even put into git. And
+specifically, it's only suitable for text files where a naive "union
+merge" is the right thing. To be precise, a nogit merge will always
+silently give you "both sides" of any merge conflict, and will not
+provide any conflict markers, (it won't even indicate that any
+conflict happened). It also won't give any predictable behavior on the
+ordering of lines in cases like this. So if your data isn't safe
+against that kind of corruption, then you'll probably not want to use
+it with nogit.
+
+The original data for which nogit was invented for was a simple TODO
+list where different people were adding items they wanted to work on,
+then removing them when they completed them. These people wanted to
+keep each other informed about their activities, so they wanted to
+share items in a single file. But there was no functional significance
+to the order of items. Finally, it was unlikely that two people would
+edit any one item in two different ways, (and even if they did it
+would be trivial and painless to sort this out after the fact).
+
 Installation
 ============
 The nogit implementation is a simple bash script named "nogit". To
@@ -52,14 +74,16 @@ save it:
   ;       and recurse.
   (defun nogit-sync-if-configured ()
     (interactive)
-    (if (and
-        (buffer-file-name)
-         (file-exists-p (format "%s/../.nogit" (buffer-file-name)))
-         (not (boundp 'in-nogit-sync))
-         )
-        (let ((in-nogit-sync t))
-          (message (substring (shell-command-to-string "nogit sync") 0 -1))
-          (revert-buffer nil t)
+    (save-match-data
+      (if (and
+           (buffer-file-name)
+           (file-exists-p (format "%s/../.nogit" (buffer-file-name)))
+           (not (boundp 'in-nogit-sync))
+           )
+          (let ((in-nogit-sync t))
+           (message (substring (shell-command-to-string "nogit sync") 0 -1))
+            (revert-buffer nil t)
+            )
         )
       )
     )
@@ -73,28 +97,15 @@ save it:
 Preparing git repositories for use with nogit
 =============================================
 If you're interested in setting up a parent and child repository for
-use with nogit, here's what you'll want to do:
-
-    In the parent repository
-    ------------------------
-    Add the following to .gitignore:
-       .nogit
-       .gitattributes
-       Any files to be tracked in the child nogit repository
-
-    For the child repository
-    ------------------------
-    Create a new git repository
-    Add the files to be tracked via nogit
-    Add a .gitattributes file with contents such as:
-
-	* merge=union
-
-    The * is a pattern to match the files you're tracking. You don't
-    necessarily need to use '*' you can explicitly name the files of
-    interest. But the important thing is that all files tracked by
-    nogit use the "union" merge driver (so that merges don't result in
-    conflicts requiring user intervention).
+use with nogit, there's almost nothing to it. In the child repository,
+just put all of the files you want to be treated with nogit's
+semantics. You don't need to fiddle with any .gitattributes or
+merge=union configuration. The nogit clone will do everything
+necessary for you so you get those semantics.
+
+Then, in the parent repository, you'll simply want to augment your
+.gitignore file to ignore all nogit-managed files from the child
+repository as well as the ".nogit" directory itself.
 
 Motivation
 ==========