From 9967de4efa603bf35cfd9fea55d7a9d8ef40e1fb Mon Sep 17 00:00:00 2001 From: Tim Byrne <sultan@locehilios.com> Date: Sun, 19 Jul 2015 13:01:52 -0500 Subject: [PATCH] Refine documentation --- README.md | 34 ++++++++++++++++++++++++---------- yadm.1 | 4 ++-- yadm.md | 4 ++-- 3 files changed, 28 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index dcd5ce59..bb1e1703 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ _A house that does not have one warm, comfy chair in it is soulless._ --May Sart When you live in a command line, configurations are a deeply personal thing. They are often crafted over years of experience, battles lost, lessons learned, advice followed, and ingenuity rewarded. When you are away from your own configurations, you are an orphaned refugee in unfamiliar and hostile surroundings. You feel clumsy and out of sorts. You are filled with a sense of longing to be back in a place you know. A place you built. A place where all the short-cuts have been worn bare by your own travels. A place you proudly call... `$HOME`. ## Introduction -_Seek home for rest, for home is best._ --Thomas Tusser +_Home is an invention on which no one has yet improved._ --Ann Douglas As so many others, I started out with a repository and a few scripts to symbolically link them around my home directory. This quickly became inadequate and I looked for solutions elsewhere. I've used two excellent tools; [homeschick](https://github.com/andsens/homeshick), and [vcsh](https://github.com/RichiH/vcsh). These tools are great, and you should check them out to understand their strengths. However, I didn't find all of the features I personally wished for in a single tool. **yadm** was written with the following goals: @@ -17,7 +17,8 @@ As so many others, I started out with a repository and a few scripts to symbolic ## Getting Started _I would not change my blest estate for all the world calls good or great._ --Isaac Watts -If you know how to use Git, then you already [know](yadm.md) how to use **yadm**. +If you know how to use Git, then you already know how to use **yadm**. +See the [man page](yadm.md) for a comprehensive explanation of commands and options. #### If you don't currently have a repository @@ -39,27 +40,24 @@ This `clone` will attempt to merge your existing repository, but if it fails, it yadm clone <url> yadm status - -See the [man page](yadm.md) for a comprehensive explanation of commands and options, but the following should be enough to get you started. - ## Strategies for alternate files on different systems -_I dislike feeling at home when I am abroad._ --George Bernard Shaw +_To feel at home, stay at home._ --Clifton Fadiman Where possible, you should try to use the same file on every system. Here are a few examples: -### Vim +### .vimrc let OS=substitute(system('uname -s'),"\n","","") if (OS == "Darwin") " do something that only makes sense on a Mac endif -### Tmux +### .tmux.conf # use reattach-to-user-namespace as the default command on OSX if-shell "test -f /usr/local/bin/reattach-to-user-namespace" 'set -g default-command "reattach-to-user-namespace -l bash"' -### Bash +### .bash_profile system_type=$(uname -s) if [ "$system_type" = "Darwin" ]; then @@ -70,7 +68,7 @@ Where possible, you should try to use the same file on every system. Here are a However, sometimes the type of file you are using doesn't allow for this type of logic. If a configuration can do an "include", you can include a specific alternate version using **yadm**. Consider these three files: -### Git +### .gitconfig #---- .gitconfig ----------------- [log] @@ -90,4 +88,20 @@ However, sometimes the type of file you are using doesn't allow for this type of email = dr.byrne@work.email.com Configuring Git this way includes `.gitconfig.local` in the standard `.gitconfig`. **yadm** will automatically link the correct version based on the operation system. The bulk of your configurations can go in a single file, and you just put the exceptions in OS-specific files. + +Of course, you can use **yadm** to manage completely separate files for different systems as well. + +### .signature + + #---- .signature## + - Tim + #---- .signature##Darwin.host1 + Sent from my MacBook + - Tim + #---- .signature##Linux.host2 + Sincerely, + Dr. Tim Byrne + +**yadm** will link the appropriate version for the current host, or use the default `##` version. + <!-- vim: set spell lbr : --> diff --git a/yadm.1 b/yadm.1 index e2942140..f794b213 100644 --- a/yadm.1 +++ b/yadm.1 @@ -341,8 +341,8 @@ After files are decrypted, permissions are automatically updated as described in the PERMISSIONS section. .BR NOTE : -It is recommended that you keep confidential files in a private repository, -even though they are encrypted. +It is recommended that you use a private repository when keeping confidential +files, even though they are encrypted. .SH PERMISSIONS When files are checked out of a Git repository, their initial permissions are dependent upon the user's umask. This can result in confidential files with lax permissions. diff --git a/yadm.md b/yadm.md index b14542a0..cc30a262 100644 --- a/yadm.md +++ b/yadm.md @@ -219,8 +219,8 @@ provide the correct password. After files are decrypted, permissions are automatically updated as described in the PERMISSIONS section. - NOTE: It is recommended that you keep confidential files in a private - repository, even though they are encrypted. + NOTE: It is recommended that you use a private repository when keeping + confidential files, even though they are encrypted. ## PERMISSIONS When files are checked out of a Git repository, their initial permis-