Initial draft.

1 files changed, 111 insertions, 0 deletions

diff --git a/USE.md b/USE.md
new file mode 100644
index 0000000..89f3ce7
--- /dev/null
+++ b/USE.md
@@ -0,0 +1,111 @@
+# Using digital media masters
+
+
+## Git annex
+
+Media masters - photos, videos, music - is tracked with git and git-annex.
+
+Git is a version control system -
+a repository for historic versions of file contents of a folder.
+Git-annex is an extension to git,
+better handling large files.
+
+
+### Paths
+
+You are recommended to use path suffix "annex"
+for media master projects.
+Examples:
+
+  * ~/public_annex/home-videos
+  * ~/private_annex/friends-snoring
+  * ~/shared_annex_family/xmas_photos
+
+
+## Create
+
+
+To turn a folder into a git repository,
+go into the folder,
+and initialize its git and git-annex databases:
+
+	git init
+	git annex init
+
+To use git-annex only for large files (git for smaller ones),
+add e.g. the following to .gitattributes
+(and (save)[#Save] that file):
+
+	* annex.largefiles=(largerthan=100kb)
+
+Alternatively,
+(clone)[#Clone] an existing project.
+
+
+## Status
+
+To check status of metadata, use git:
+
+	git status
+
+To check status of file content storage, use git-annex:
+
+	git annex info
+
+
+## Save
+
+To "take a snapshot" of one of more files
+for git-annex archival,
+first mark which files are involved
+and then archive their (changes to) content:
+
+	git annex add foo bar
+	git annex add baz
+	git commit -m "Update foo bar, and add baz."
+
+Alternatively you can update (but not add)
+in one go:
+
+	git commit -m "Update foo bar." foo bar
+
+
+## Clone
+
+To collaborate on a shared git repository,
+first create a local clone from the shared location,
+and then FIXME:
+
+	git clone git://[[!template id=githost]]/example
+	git annex FIXME
+
+Then from time to time syncronize:
+
+	git annex sync --content --all
+
+Alternatively (e.g. on slow/expensive network),
+syncronize only metadata and only with nearest clones:
+
+	git annex sync --fast
+
+
+### Publish
+
+To publish a git repository initially created locally,
+first create a new empty git and git annex publicly,
+then tell your local git where its new origin will be,
+and finally push your local git and git annex into its new public location:
+
+	ssh [[!template id=githost]] git init --bare --shared /srv/git/[[!template id=githost]]/example.git
+	ssh [[!template id=githost]] GIT_DIR=/srv/git/[[!template id=githost]]/example.git git annex init
+	git remote add origin [[!template id=githost]]:/srv/git/[[!template id=githost]]/example.git
+	git push --set-upstream origin master
+	git annex sync --content --all
+
+
+## References
+
+* [media-master][Source of this document]
+
+[media-master]: <https://source.redpill.dk/media-master>.
+  "Digital media master material"