From 88084aa515b92d5889b73b60950dee9fcbcf60a7 Mon Sep 17 00:00:00 2001 From: Gernot Schulz Date: Fri, 11 Nov 2011 16:30:12 +0100 Subject: [PATCH] Make Markdown source easier to read --- INSTALL.md | 35 ++++++++++++++---------- README.md | 78 ++++++++++++++++++++++++++++++++++-------------------- 2 files changed, 71 insertions(+), 42 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 4979ca1..16db617 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -11,7 +11,8 @@ Below, you will find a few different methods for setting up vcsh: ## 1.1 Prerequisites ## -Make sure none of the following files/diretories exist for your test (user). If they do, move them away for now: +Make sure none of the following files/diretories exist for your test (user). If +they do, move them away for now: * ~/.gitignore * ~/.mrconfig @@ -20,7 +21,8 @@ Make sure none of the following files/diretories exist for your test (user). If * ~/.config/mr/config.d/mr.vcsh * ~/.config/vcsh/repo.d/mr.git/ -All of the files are part of the template repository, the directory is where the template will be stored. +All of the files are part of the template repository, the directory is where +the template will be stored. apt-get install mr # this is optional, but highly recommended @@ -76,14 +78,16 @@ Neat. ### 1.5.2 Making changes ### -After you have made some changes, for which you would normally use `git add` and `git commit`, use the vcsh wrapper (like above): +After you have made some changes, for which you would normally use `git add` +and `git commit`, use the vcsh wrapper (like above): vcsh run foo git add -f bar baz quux vcsh run foo git commit vcsh run foo git push -By the way, you'll have to use -f/--force flag with git-add because all files will be ignored by default. This is to show you only useful output when running git-status. -A fix for this problem is being worked on. +By the way, you'll have to use -f/--force flag with git-add because all files +will be ignored by default. This is to show you only useful output when running +git-status. A fix for this problem is being worked on. # 2. The steal-from-template way # @@ -92,12 +96,14 @@ You're welcome to clone the example repository: git clone git://github.com/RichiH/vcsh_mr_template.git -Look around in the clone. It should be reasonably simple to understand. If not, poke me, RichiH, on Freenode (query) or OFTC (#vcs-home). +Look around in the clone. It should be reasonably simple to understand. If not, +poke me, RichiH, on Freenode (query) or OFTC (#vcs-home). # 3. The manual way # -This is how my old setup procedure looked like. Adapt it to your own style or copy mine verbatim, either is fine. +This is how my old setup procedure looked like. Adapt it to your own style or +copy mine verbatim, either is fine. # Create workspace mkdir -p ~/work/git @@ -132,9 +138,10 @@ mr is used to actually retrieve configs, etc # 4. Using vcsh without mr # -vcsh encourages you to use mr. -It helps you manage a large number of repositories by running the necessary vcsh commands for you. -You may choose not to use mr, in which case you will have to run those commands manually or by other means. +vcsh encourages you to use mr. It helps you manage a large number of +repositories by running the necessary vcsh commands for you. You may choose not +to use mr, in which case you will have to run those commands manually or by +other means. ## 4.1 A few examples ## @@ -142,15 +149,15 @@ To initialize a new repository: `vcsh init zsh` To clone a repository: `vcsh clone ssh:///zsh.git` -To interact with a repository, use the regular Git commands, but prepend them with `vcsh run $repository_name`. -For example: +To interact with a repository, use the regular Git commands, but prepend them +with `vcsh run $repository_name`. For example: vcsh run zsh git status vcsh run zsh git add -f .zshrc vcsh run zsh git commit -Obviously, without mr keeping repositories up-to-date, it will have to be done manually. -Alternatively, you could try something like this: +Obviously, without mr keeping repositories up-to-date, it will have to be done +manually. Alternatively, you could try something like this: for repo in `vcsh list`; do vcsh run $repo git pull; diff --git a/README.md b/README.md index 0a9b172..21b22d9 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,13 @@ vcsh - manage and sync config files via git # Introduction # -vcsh allows you to have several git repositories, all maintaining their working trees in $HOME without clobbering each other. -That, in turn, means you can have one repository per config set (zsh, vim, ssh, etc), picking and choosing which configs you want to use on which machine. +vcsh allows you to have several git repositories, all maintaining their working +trees in $HOME without clobbering each other. That, in turn, means you can have +one repository per config set (zsh, vim, ssh, etc), picking and choosing which +configs you want to use on which machine. -vcsh was designed with mr [1] in mind so you might want to install that, as well. +vcsh was designed with mr [1] in mind so you might want to install that, as +well. Read INSTALL.md for detailed setup instructions. @@ -13,20 +16,26 @@ Questions? RichiH@{Freenode,OFTC,IRCnet} ## Comparison to Other Solutions ## -Most people who decide to put their dotfiles under version control start with a **single repository in $HOME**, adding all their dotfiles (and possibly more) to it. -This works, of course, but can become a nuisance as soon as you try to manage more than one host. +Most people who decide to put their dotfiles under version control start with a +**single repository in $HOME**, adding all their dotfiles (and possibly more) +to it. This works, of course, but can become a nuisance as soon as you try to +manage more than one host. -The next logical step is to create single-purpose repositories in, for example, ~/.dotfiles and to create **symbolic links in $HOME**. -This gives you the flexibility to check out only certain repositories on different hosts. -The downsides of this approach are the necessary manual steps of cloning and symlinking the individual repositories. -It will probably become a nuisance when you try to manage more than two hosts. +The next logical step is to create single-purpose repositories in, for example, +~/.dotfiles and to create **symbolic links in $HOME**. This gives you the +flexibility to check out only certain repositories on different hosts. The +downsides of this approach are the necessary manual steps of cloning and +symlinking the individual repositories. It will probably become a nuisance when +you try to manage more than two hosts. -**vcsh** takes this second approach one step further. -It expects **single-purpose repositories** and stores them in a hidden directory (similar to ~/.dotfiles). -However, it does not create symbolic links in $HOME; it puts the **actual files right into $HOME**. +**vcsh** takes this second approach one step further. It expects +**single-purpose repositories** and stores them in a hidden directory (similar +to ~/.dotfiles). However, it does not create symbolic links in $HOME; it puts +the **actual files right into $HOME**. -Furthermore, by making use of mr [1], it makes it very easy to enable/disable and clone a large number of repositories. -The use of mr is technically optional, but it will be an integral part of the proposed system that follows. +Furthermore, by making use of mr [1], it makes it very easy to enable/disable +and clone a large number of repositories. The use of mr is technically +optional, but it will be an integral part of the proposed system that follows. ## Default Directory Layout ## @@ -68,9 +77,12 @@ In this setup, ~/.mrconfig looks like: jobs = 5 include = cat ~/.config/mr/config.d/* -The files you see in ~/.config/mr/available.d are mr configuration files that contain the commands to manage (checkout, update etc.) a single repository. -vcsh repo configs end in .vcsh, git configs end in .git, etc. This is optional and your preference. -For example, this is what a zsh.mrconfig with read-only access to my zshrc repo looks likes. I.e. in this specific example, push can not work. +The files you see in ~/.config/mr/available.d are mr configuration files that +contain the commands to manage (checkout, update etc.) a single repository. +vcsh repo configs end in .vcsh, git configs end in .git, etc. This is optional +and your preference. For example, this is what a zsh.mrconfig with read-only +access to my zshrc repo looks likes. I.e. in this specific example, push can +not work. [$HOME/.config/vcsh/repo.d/zsh.git] checkout = vcsh clone 'git://github.com/RichiH/zshrc.git' @@ -78,28 +90,38 @@ For example, this is what a zsh.mrconfig with read-only access to my zshrc repo push = vcsh run bash git push status = vcsh run bash git status -~/.config/mr/available.d contains *all available* repositories. -Only files/links present in mr/config.d, however, will be used by mr. -That means that in this example, only the zsh, gitconfigs, tmux and vim repositories will be checked out. -A simple `mr update` run in $HOME will clone or update those four repositories listed in config.d. +~/.config/mr/available.d contains *all available* repositories. Only +files/links present in mr/config.d, however, will be used by mr. That means +that in this example, only the zsh, gitconfigs, tmux and vim repositories will +be checked out. A simple `mr update` run in $HOME will clone or update those +four repositories listed in config.d. -~/.config/vcsh/repo.d is the directory into which vcsh clones the git repositories. -Since their working trees are configured to be in $HOME, the files contained in those repositories will be put in $HOME directly (see .zshrc above). +~/.config/vcsh/repo.d is the directory into which vcsh clones the git +repositories. Since their working trees are configured to be in $HOME, the +files contained in those repositories will be put in $HOME directly (see .zshrc +above). -vcsh will check if any file it would want to create exists. If it exists, vcsh will throw a warning and exit. Move away your old config and try again. Optionally, merge your local and your global configs afterwards and push with `vcsh run foo git push`. +vcsh will check if any file it would want to create exists. If it exists, vcsh +will throw a warning and exit. Move away your old config and try again. +Optionally, merge your local and your global configs afterwards and push with +`vcsh run foo git push`. ## Moving into a New Host ## -To illustrate further, the following steps could move your desired configuration to a new host. +To illustrate further, the following steps could move your desired +configuration to a new host. -1. Clone the mr repository (containing available.d, config.d etc.). For example: `vcsh clone git://github.com/RichiH/vcsh_mr_template.git` -2. Choose your repositories by linking them in config.d (or go with the default you may have already configured by adding symlinks to git). +1. Clone the mr repository (containing available.d, config.d etc.). For + example: `vcsh clone git://github.com/RichiH/vcsh_mr_template.git` +2. Choose your repositories by linking them in config.d (or go with the default + you may have already configured by adding symlinks to git). 3. Run mr to clone the repositories: `cd; mr update`. 4. Done. Hopefully the above could help explain how this approach saves time by -1. making it easy to manage, clone and update a large number of repositories (thanks to mr) and +1. making it easy to manage, clone and update a large number of repositories + (thanks to mr) and 2. making it unnecessary to create symbolic links in $HOME (thanks to vcsh). ---------- -- 2.39.5