Update README.md

Moved the rest to wiki.

Author: cdunn2001

README.md

@@ -19,136 +19,34 @@ Alternatively, you can run it directly:
 python git_sym.py -h
 ```
 
-## Examples
-These examples explain the basics:
-
-* <https://github.com/cdunn2001/git-sym-test/wiki/Examples>
-
-## Running
-You can test it right here. The `links` directory has some examples.
-```
-$ ls -l links/foo
-lrwxr-xr-x  1 cdunn2001  staff  15 Jun 10 09:44 links/foo -> ../.git_sym/foo
-```
-For this example, a file called `foo` needs to exist in your home directory,
-because that is where our makefile looks for it:
-```
-$ cat git_sym.makefile
-foo:
-	cp -f ~/foo $@
-
-$ touch ~/foo
-```
-Then, just run `git-sym update`:
-```
-git-sym update links/foo
-# or
-# python git_sym.py update links/foo
-cat links/foo
-```
-
-## How it works
-* Instead of a large file, create a symlink to `.git_sym/unique_filename`.
-```
-ln -sf .git_sym/unique_filename my_filename
-```
-* Add a rule to `git_sym.makefile` which can retrieve `unique_filename`.
-```
-unique_filename:
-	wget http://mysite.com/unique_filename
-```
-* Then, `git-sym update` will automatically retrieve the file and fill in the symbolic links.
+## Basic usage
+### For repo users
 ```
 git-sym update
 ```
-
-## Breaking the link
-To break it, remove the file from the cache and from its
-origin.
+### For repo owners
 ```
-rm -f ~/git_sym_cache/foo ~/foo .git_sym
+git-sym add my_big_file.gif
+git commit -m 'git-sym added'
+ls -l my_big_file.gif
 ```
-Then, this should fail:
+Or more explicitly, and with a rule for retrieval:
 ```
+ln -sf .git_sym/my_big_data.v123.db my_big_data.db
+git add my_big_data.db
+git commit
+cat <<EOF >> git_sym.makefile
+my_big_data.v123.db:
+        wget http://www.somewhere.com/my_big_data.v123.db
+EOF
 git-sym update
 ```
 
-## Adding your own large-files.
-```
-git-sym add large1 large2 large3
-git commit -m 'adding links'
-git-sym show
-```
-**git-sym** will choose unique filenames based on checksums. But `git-sym add` is strictly for convenience.
-You are free to use your own filenames. Anything symlinked via `GIT_ROOT/.git_sym` will be update-able.
-
-Next, you might want to make those files available to other.
-You can then move those files out of GIT_SYM_CACHE_DIR and into Amazon S3, or an ftp site, or wherever.
-Just add rules to your `git_sym.makefile`.
-
-## Other useful commands
-```
-git-sym show -h
-git-sym missing -h
-git-sym -h
-```
-
-# Details
-## Typical usage
-You will store relative symlinks in your repo. They will point to a unique filename inside `ROOT/.git_sym/`, where ROOT is `../../` etc.
-
-`git-sym update` will search your repo for symlinks (unless you specify them on the command-line). For each, it will execute `ROOT/git_sym.makefile` in your `GIT_SYM_CACHE_DIR` (`~/git_sym_cache` by default). The makefile targets will be the basenames of the symlinks.
-
-If all those files are properly retrieved, then symlinks will be created with the same filenames inside `.git/git_sym`. `ROOT/.git_sym` will point at that. And all other symlinks will point *thru* `ROOT/.git_sym`. Thus, there are three (3) levels of indirection.
-
-## Makefile
-Someday, we will offer a plugin architecture. But for now, using a makefile is really very simple. Just create a rule for each unique filename. (You *are* using unique filenames, right?) You can run `wget`, `curl`, `ftp`, `rcp`, `rsync`, `aws-s3-get`, or whatever you want. The retrieval mechanism is decoupled from caching.
-
-You should try to ensure that you have a rule for every current symlink. Old rules for symlinks no longer in your repo are fine; they are simply ignored.
-
-To test your rules:
-```
-export GIT_SYM_CACHE_DIR=~/mytest
-git-sym missing # should report something
-git-sym update
-git-sym missing
-```
-
-## Other notes
-### Cache
-**git-sym** sets the mode to read-only for the cached files. These files should never change. You might want to name them after their own checksums. `git-sym add` can help you with that.
-### Submodules
-If your module can be used as a *submodule*, we cannot point at `.git/git_sym/` directly because for submodules `.git/` is not inside the tree. (The relative symlinks are constant, so they need to work no matter where `.git/` sits.) That is why we have *three* levels of indirection, in case your were wondering. (This is also why **git-annex** *fails* for submodules.)
-
-This is also why we write `ROOT/.git_sym`; it might be a different directory than `.git`.
-
-For submodule support, you will also need this:
-```
-git config --global alias.gsexec '!exec '
-```
-We use that to learn the actual location of the `.git/` directory. If it fails, we try current directory, and if `.git` is not a directory there, we attempt to find it in `../.git/modules/REPO`, where REPO is the root directory. (This can fail in many ways. The alias never fails.)
-
-Again, we expect you to forget that, so we add that alias to your local repo for you. Believe us: It's a Good Thing.
-
-### git-sym-test
-This module provides a way to test **git-sym**. It is not required.
-However, it is listed as a git-submodule here for conveniently
-testing submodule support.
-```
-git submodule update --init
-```
-
-### .gitignore
-Since the intermediate symlink is also in the repo, but points to a changing target, it needs to be listed in `.gitignore`. (That anticipates both accidental `git add` and `git clean`.) We expect you to forget that important rule, so **git-sym** will detect its absence and add it to `.git/info/exclude` instead. No worries.
-
-### Complicated symlinks?
-We require a flat directory structure within `.git/git_sym`. If you need more files than your filesystem
-can handle, you're Doing It Wrong. Git will slow down anyway.
+## Examples
+These examples explain the basics:
 
-However, we support symlinked *directories*, which can then be an entire tree in GIT_SYM_CACHE_DIR. That should
-satisfy all reasonable use-cases.
+* <https://github.com/cdunn2001/git-sym-test/wiki/Examples>
 
-# TODO
-* git-sym fix -- also fix broken links from moved cache, and missing links in GIT_SYM_DIR
-* Try `.gitattributes` instead of `.gitignore`, to avoid problems with `git clean`.
-* Add `git-submodule` support, to run `git-sym update` automatically.
+If you prefer words to shell code:
+* <https://github.com/cdunn2001/git-sym/wiki/Details>
+* <https://github.com/cdunn2001/git-sym/wiki/Examples>