Add a README.md

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..42e16dd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,54 @@
+# Steve's dotfiles
+
+The dotfiles are largely self explanatory.
+
+## Installing and using the dotfiles repository
+
+cd ~
+git clone url-path-to-dotfiles.git .dotfiles
+git submodule init
+git submodule update
+.dotfiles/install.sh
+
+The install.sh script installs symbolic links from various dotfiles' normal file
+locations to their location within the .dotfiles/ directory.
+
+## Updating the dotfiles repository
+
+cd ~/.dotfiles
+git pull --rebase
+git submodule update
+./install.sh
+
+## About install.sh
+
+Dotfiles are expected to be located in the user's home directory, or under some
+path from the home directory.  Certainly not in .dotfiles/.  The install.sh
+script creates symbolic links from the expected location of each dot file to its
+actual location within .dotfiles/.  For safety, install.sh will only create a
+new symbolic link, or replace an existing symbolic link; it will not remove dot
+files that are actual files.
+
+## Vim plugins
+
+Vim plugins are each a git submodule.  To add a new git plugin, find or make a
+git repository for it, then add it as a submodule:
+
+cd ~/.dotfiles
+git submodule add url-path-to-plugin.git vim/bundle/plugin
+
+Vim builds doc/tags files in each plugin directory.  Be sure this file is
+silently ignored by the git 'super' module by editing the .gitmodules file and
+adding an ignore for untracked files, "ignore = tracked".  An example is shown
+below.
+
+[submodule "vim/bundle/plugin"]
+       path = vim/bundle/plugin
+       url = url-path-to-plugin.git
+       ignore = untracked
+
+Register and update the submodule:
+
+git submodule init
+git submodule update
+