diff options
| -rw-r--r-- | doc/how_it_works.mdwn | 41 | ||||
| -rw-r--r-- | doc/index.mdwn | 2 |
2 files changed, 42 insertions, 1 deletions
diff --git a/doc/how_it_works.mdwn b/doc/how_it_works.mdwn new file mode 100644 index 000000000..0acf20565 --- /dev/null +++ b/doc/how_it_works.mdwn @@ -0,0 +1,41 @@ +This page gives a high-level view of git-annex. For a detailed +low-level view, see [[the_man_page|git-annex]] and [[internals]]. + +You do not need to read this page to get started with using git-annex. The +[[walkthrough]] provides step-by-step instructions. + +Still reading? Ok. Git's man page calls it "a stupid content +tracker". With git-annex, git is instead "a stupid filename and metadata" +tracker. The contents of large files are not stored in git, only the +names of the files and some other metadata remain there. + +The contents of the files are kept by git-annex in a distributed key/value +store consisting of every clone of a given git repository. That's a fancy +way to say that git-annex stores the actual file content somewhere under +`.git/annex/`. (See [[internals]] for details.) + +That was the values; what about the keys? Well, a key is calculated for a +given file when it's first added into git-annex. Normally this uses a hash +of its contents, but various [[backends]] can produce different sorts of +keys. The file that gets checked into git is just a symlink to the key +under `.git/annex/`. If the content of a file is modified, that produces +a different key (and the symlink is changed). + +A file's content can be [[transferred|transferring_data]] from one +repository to another by git-annex. Which repositories contain a given +value is tracked by git-annex (see [[location_tracking]]). It stores this +tracking information in a separate branch, named "git-annex". All you ever +do with the "git-annex" branch is push/pull it around between repositories, +to [[sync]] up git-annex's view of the world. + +That's really all there is to it. Oh, there are [[special_remotes]] that +let values be stored other places than git repositories (anything from +Amazon S3 to a USB key), and there's a pile of commands listed in +[[the_man_page|git-annex]] to handle moving the values around and managing +them. But if you grok the description above, you can see through all that. +It's really just symlinks, keys, values, and a git-annex branch to store +additional metadata. + +--- + +Next: [[install]] or [[walkthrough]] diff --git a/doc/index.mdwn b/doc/index.mdwn index e0791bf71..50d48a5f7 100644 --- a/doc/index.mdwn +++ b/doc/index.mdwn @@ -1,6 +1,6 @@ [[!inline raw=yes pages="summary"]] -To get a feel for it, see the [[walkthrough]]. +To get a feel for it, see the [[walkthrough]] or read about [[how_it_works]]. [[!sidebar content=""" [[!img logo_small.png link=no]] |