Rename HOWTO → USE.

1 files changed, 78 insertions, 0 deletions

diff --git a/USE.md b/USE.md
new file mode 100644
index 0000000..93aed5e
--- /dev/null
+++ b/USE.md
@@ -0,0 +1,78 @@
+# Using digital source material
+
+> Use the source, Luke
+>
+> -- a [pun][UTSL] on Obi-Wan Kenobi quote in Star Wars
+
+
+## Git
+
+Digital source material is tracked with git.
+
+Git is a version control system -
+a repository for historic versions of file contents of a folder.
+
+
+
+## Create
+
+
+To turn a folder into a git repository,
+go into the folder,
+and initialize its git database:
+
+	git init
+
+
+## Save
+
+
+To "take a snapshot" of one of more files
+for git archival,
+first mark which files are involved
+and then archive their (changes to) content:
+
+	git add foo bar
+	git 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
+
+
+## Share
+
+To collaborate on a shared git repository,
+first create a local copy from the shared location:
+
+	git clone git://[[!template id=githost]]/example
+
+Then from time to time syncronize,
+first fetch eventual updates from others
+and then push your local changes:
+
+	git pull
+	git push
+
+### Publish
+
+To publish a git repository initially created locally,
+first create a new empty git publicly,
+then your existing local git where its new origin will be,
+and finally push your git into its new location:
+
+	ssh [[!template id=githost]] git init --bare --shared /srv/git/[[!template id=githost]]/example.git
+	git remote add origin [[!template id=githost]]:/srv/git/[[!template id=githost]]/example.git
+	git push --set-upstream origin master
+
+
+## References
+
+* [source][Source of this document]
+
+[UTSL]: <http://catb.org/jargon/html/U/UTSL.html>
+
+[source]: <https://source.redpill.dk/source>.
+  "Digital source material"