dotmodule 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: afb5ce73d11f4c18dab49f48ef961de191d90aac
-  data.tar.gz: 35b34b660806d538df722e3380f53d1a35ddaba4
+  metadata.gz: 97a5f89a98b981463d33e24efb62b8027fe11064
+  data.tar.gz: 29f5b4893fe4355a1ab607566761abd20d9d5471
 SHA512:
-  metadata.gz: 2f942872744724b7ee18100dae0db5e586aa37e9f900cc2bf94efe2f6eb2b81c837b825db3eb9cb75b5139d010aeb6964c385044be92cdb7334e382952503ec8
-  data.tar.gz: 1c6876fe409f3ce28cee0ee89009ef235dce4f618aadb8b9d4eac67657b9179695b83852e31ebac0e3e43de91e2224609818864cda03a3815ae79e3357ecda21
+  metadata.gz: 54885352278cd8a5f1dc30adf05446d2028e3ffb43e368038ac4bd34ab5ab7d4697a891a483673577e0263fba78fc80dbf81bfcf24b594d1097bdcc896b83445
+  data.tar.gz: 2b0a4f1f1800763430233ea4dd4c1c5c50f777f9e0b5e091174415f5c8e4c6de44210e59c0fa09778248a3492e9409131e2f4a3e092b8a4294404e3938d96996

data/README.md

@@ -1,38 +1,128 @@
 # Dotmodule
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/dotmodule`. To experiment with that code, run `bin/console` for an interactive prompt.
+## Overview
 
-TODO: Delete this and the text above, and describe your gem
+This is a simple management helper for modular dotfile repositories.
+
+It decorates [GNU Stow](https://www.gnu.org/software/stow/) with a couple of minor but useful (to me) features:
+- Pre- and post- installation scripts (e.g. to check out other projects from git -- i.e. spacemacs)
+- Shared directory configuration via an optional config file (to safeguard against collisions between GNU Stow and other applications -- more detail below)
+- Defining a subset of 'core' modules to be installed on all systems
+
+This can be used with an existing stow link farm as-is, adding use of new features as needed on a per-module basis.
+
+The (optional) configuration file is `dotmodule.collection`, a file in YAML format located at the collection root.
+It is only required if defining shared folders and/or a core module set.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+    $ gem install dotmodule
+
+## Usage
+
+### Basic usage
+
+Organise your dotfiles in modules, one per directory (i.e. a standard link farm for GNU Stow). Given a dotmodule collection at ~/dotfiles...
 
-```ruby
-gem 'dotmodule'
 ```
+$ cd ~/dotfiles
+ 
+$ dotmodule install
 
-And then execute:
+ Collection root:    /home/cormacc/dotfiles
+ Default target:     /home/cormacc
 
-    $ bundle
+ Shared target subdirectories:
+   bin, .config, .profile.d
 
-Or install it yourself as:
+ Modules:
+   i3, vscode, fish, ruby, zsh, emacs, xorg, base, ssh, macbook
 
-    $ gem install dotmodule
+ Core modules:
+   base, zsh, emacs, ssh, ruby
 
-## Usage
 
-TODO: Write usage instructions here
+No module argument passed. Install (c)ore/(a)ll/(n)one? [n]: c
+Installing 5 modules ...
+.. Module base ..
+.. Module zsh ..
+.. Module emacs ..
+... running hook 'pre': '/home/cormacc/dotfiles/emacs-pre'
+.... WARNING: ~/.emacs.d found -- skipping spacemacs checkout
+.. Module ssh ..
+.. Module ruby ..
+
+```    
+
+N.B. Shared target subdirectories and core modules will be blank, unless configured in the optional collection config file
+
+To install a specific module or modules
+
+    $dotmodule install MODULE_NAME
+
+or
+
+    $dotmodule install MODULE_NAME, ANOTHER_MODULE_NAME
+
+To display module collection parameters
+
+    $dotmodule info
+
+
+### Pre- and post-installation hooks (Optional)
+
+Any file in the farm root matching the pattern '<modulename>-pre' or '<modulename>-post' will be treated as a pre- or post-
+installation hook and executed before/after GNU stow. I use an 'emacs-pre' hook to clone the spacemacs repository. Similarly, could use a pre or post hook to copy your ssh keys from somewhere else (as you probably don't want them in a public dotfile repo).
+
+
+### Shared folders (Optional)
+
+GNU Stow is clever at managing collisions between modules in a link farm, however we can run into issues when constructing symlinks into directory trees that are used by multiple applications -- e.g. `~/.config` -- resulting in unwanted data in your dotfile repo. To guard against this, you can declare these shared directories as a YAML list in a file called `dotmodule.collection` located at the root of your dotfile repository.
+
+```yaml
+:shared_directories:
+  - bin
+  - .config
+  - .profile.d
+  - this/also/works/with/nested/paths
+```
+
+The `dotmodule` gem will ensure these directories are created before installing any modules to prevent GNU Stow from creating them as links into your dotfile repository instead.
+
+### Core modules (Optional)
+
+This is purely a convenience -- allowing you to quickly install essential modules without having to remove modules that are platform-specific you're not using any more but may again at a later date from your repo. These core modules are also defined in `dotmodule.collection`
+
+```yaml
+:core_modules:
+  - base
+  - zsh
+  - emacs
+  - ssh
+  - ruby
+```
+
+### Examples
+
+See [my dotfiles](https://github.com/cormacc/dotfiles) for an example.
+
+
+## Development / improvements
+
+This is a pretty basic gem.
+
+The majority of the functionality is defined in [DotModule::Collection](lib/dotmodule.rb)
 
-## Development
+This is wrapped in a basic [CLI](lib/dotmodule/CLI.rb) using [Thor](https://github.com/erikhuda/thor).
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Unlike GNU Stow, the installation target directory is always the user home directory (internally, `Dir.home`) rather than the parent directory of the module collection.  `DotModule::Collection` is setup to allow explicit target specification, but the CLI wrapper doesn't yet,
+as I don't currently need it to. That said, it would probably only take slightly more time to change that than it has to write this paragraph :)
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+If you add to a module, you can just `dotmodule install` it again. However if you remove content you need to clean out stale links manually. Might be worth adding some logic to detect/delete stale links, and/or uninstall a module.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/dotmodule.
+Bug reports and pull requests are welcome on GitHub at https://github.com/cormacc/dotmodule.
 
 
 ## License

data/lib/dotmodule.rb

@@ -49,7 +49,7 @@ module DotModule
     # Currently, this supports a single array entry listing any folders shared with other applications / the system
     def load_config
       file = root+CONFIG_FILE_NAME
-      @config = file.file? ? YAML.load_file(file) : { :shared_directories => nil, :core_modules => nil }
+      @config = file.file? ? YAML.load_file(file) : { :shared_directories => [], :core_modules => [] }
     end
     
     def modules
@@ -65,7 +65,7 @@ module DotModule
     end
 
     def default_target
-      @root.parent
+      Pathname.new(Dir.home)
     end
 
     def create_shared_directories(target_root)
@@ -80,10 +80,11 @@ module DotModule
 
     def install_module(name, target=default_target)
       create_shared_directories(target)
-      puts "... installing #{name} ..."
+      puts ".. Module #{name} .."
       raise ArgumentError, "Module '#{name}' not found" unless (@root+name).directory?
-
+      preinstall(name)
       system "stow -d #{@root} -t #{target} #{name}"
+      postinstall(name)
     end
 
     def install_modules(module_names, target=default_target)
@@ -103,22 +104,42 @@ module DotModule
     end
 
     def to_s
-      <<~HEREDOC
+      # <<~HEREDOC would be nicer, but not worth sacrificing compatibility with rubies <2.3 for
+      <<-HEREDOC
 
-      Collection root:    #{@root}
-      Default target:     #{default_target}
+ Collection root:    #{@root}
+ Default target:     #{default_target}
 
-      Shared target subdirectories:
-        #{shared_directories.join(', ')}
+ Shared target subdirectories:
+   #{shared_directories.join(', ')}
 
-      Modules:
-        #{modules.join(', ')}
+ Modules:
+   #{modules.join(', ')}
 
-      Core modules:
-        #{core_modules.join(', ')}
+ Core modules:
+   #{core_modules.join(', ')}
 
       HEREDOC
     end
+
+    private
+
+    def preinstall(module_name)
+      runhook(module_name, 'pre')
+    end
+
+    def postinstall(module_name)
+      runhook(module_name, 'post')
+    end
+
+    def runhook(module_name, hook)
+      hook_file = @root + "#{module_name}-#{hook}"
+      return unless hook_file.file?
+      puts "... running hook '#{hook}': '#{hook_file}'"
+      IO.popen("sh #{hook_file}").each do |line|
+        puts ".... #{line}"
+      end
+    end
   end
 
 end

data/lib/dotmodule/version.rb

@@ -1,3 +1,3 @@
 module DotModule
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dotmodule
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Cormac Cannon
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-11-03 00:00:00.000000000 Z
+date: 2016-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor