Add dtags version 3.x

README.rst

@@ -1,16 +1,14 @@
 Features
 ========
 
-**dtags** is a lightweight command line tool which lets you:
+**dtags** is a lightweight command line tool with tab-completion which lets you:
 
 -  Tag and un-tag directories
 -  Change directories quickly via tags
--  Execute commands in tagged directories at the same time
--  Easily manage multiple git repositories, vagrant machines etc.
+-  Run commands in tagged directories at the same time
+-  Use shell variables to reference tagged directories
+-  Easily manage git repositories, vagrant machines etc.
 
-All commands come with tab-completion.
-
-.. image:: example.gif
 
 Installation
 ============
@@ -28,53 +26,41 @@ Installation
     # You may need to sudo depending on your setup
     ~$ pip install --upgrade dtags
 
-**Step 3**: Add the following line to your shell runtime configuration:
+**Step 3**: Add the following line at the end of your shell runtime configuration:
 
 .. code:: bash
 
     # For zsh, place in ~/.zshrc:
-    command -v dtags > /dev/null 2>&1 && eval "`dtags shell zsh`"
+    command -v dtags-activate > /dev/null 2>&1 && eval "`dtags-activate zsh`"
 
     # For bash, place in ~/.bashrc (or ~/.bash_profile for OS X):
-    command -v dtags > /dev/null 2>&1 && eval "`dtags shell bash`"
+    command -v dtags-activate > /dev/null 2>&1 && eval "`dtags-activate bash`"
 
     # For fish, place in ~/.config/fish/config.fish:
-    command -v dtags > /dev/null 2>&1; and dtags shell fish | source
+    command -v dtags-activate > /dev/null 2>&1; and dtags-activate fish | source
 
 **Step 4**. Restart your shell.
 
-::
-
-    Note for those who are upgrading from v1.x.x:
-    
-      dtags v2 has config changes that are not backwards-compatible.
-      If you want to keep your tags, you need to run a migration script:
-      
-       ~$ git clone https://github.com/joowani/dtags.git
-       ~$ python dtags/scripts/migrate.py
-       
-      If you don't mind losing them, simply run 'rm -rf ~/.dtags' instead.
+Once installed, you will have **5** commands at your disposal: 
+``t``, ``u``, ``d``, ``e`` and ``dtags``.
 
-Once installed, you will have **5** commands at your disposal: ``tag``,
-``untag``, ``d``, ``e`` and ``dtags``. Make sure you don't have any
-linux aliases, functions or symlinks etc. with the same names.
 
 Usage Examples
 ==============
 
-Tag directories with ``tag``:
+Tag directories with ``t``:
 
 .. code:: bash
 
-    ~$ tag ~/web dev work   # add tags 'dev' and 'work' to ~/web
-    ~$ tag ~/app            # tag ~/app with its basename, 'app'
+    ~$ t ~/web dev work     # add tags 'dev' and 'work' to ~/web
+    ~$ t ~/app              # tag ~/app with its basename, 'app'
 
-Un-tag directories with ``untag``:
+Un-tag directories with ``u``:
 
 .. code:: bash
 
-    ~$ untag ~/web dev      # remove tag 'dev' from ~/web
-    ~$ untag ~/app          # remove all tags from ~/app 
+    ~$ u ~/web dev          # remove tag 'dev' from ~/web
+    ~$ u ~/app              # remove all tags from ~/app
 
 Change directories with ``d`` (designed to fully replace ``cd``!):
 
@@ -94,53 +80,58 @@ Execute commands in one or more directories with ``e``:
     ~$ e -p vm git pull     # execute 'git pull' in directories tagged 'vm' in parallel
     ~$ e vm,~/foo ls        # execute 'ls' in directories tagged 'vm' and ~/foo
 
-Search and manage tags with ``dtags``:
+Display, search and manage tags with ``dtags``:
 
 .. code:: bash
 
     ~$ dtags                # display the directories-to-tags mapping
-    ~$ dtags list ~ ~/vm    # display the tags and directories associated with ~ and ~/app
+    ~$ dtags list ~ ~/vm    # display the tags and directories associated with ~ and ~/vm
     ~$ dtags list foo bar   # display the tags and directories associated with 'foo' or 'bar'
-    ~$ dtags reverse        # display the tags-to-directories mapping
+    ~$ dtags reverse        # display the tags-to-directories (reverse) mapping
     ~$ dtags edit           # edit tags and directories via editor like vim
     ~$ dtags clean          # remove invalid or stale tags and directories
+    ~$ dtags commands       # display all available dtags commands (e.g. t, u, d, e)
+
+
+If a tag points to a single directory, shell variables are automatically created:
+
+.. code:: bash
+
+    ~$ t ~/some/dir foo     # shell variable $foo is automatically created
+    ~$ ls $foo/sub/dir      # $foo can be used to denote the tagged directory ~/some/dir
+    ~$ rm $foo/file.sh      # $foo can be used to denote the tagged directory ~/some/dir
 
 You can always use the ``--help`` option to find out more about each command!
 
+
 Technical Notes
 ===============
 
--  Windows is currently not supported
--  The directory-to-tags mapping is saved in ``~/.dtags/mapping``
--  Tags are also saved on their own in ``~/.dtags/tags`` for
-   tab-completion
--  ``e -p`` hangs on interactive commands that wait on input (no easy
-   way around this)
+-  The directory-to-tags mapping is stored in ``~/.dtags/mapping``
+-  Tags are also stored on their own in ``~/.dtags/tags`` for tab-completion
+-  ``e -p`` is currently not supported on Windows
+-  ``e -p`` cannot execute interactive commands that wait on input
 -  ``e -p`` spawns child processes and redirects their output to
    temporary files and then to stdout
 -  ``e -p`` sends *sigterm* to its child processes when killed
--  ``e`` uses environment variable **$SHELL** to guess which shell is in
-   use
--  ``e`` redirects all stderr to stdout and should always return an exit
-   status of 0
--  ``e`` executes the commands using *interactive shell*, which has pros
-   and cons:
-
-   -  ``e`` can properly use linux functions and aliases
-   -  The shell runtime configuration must be "sourced" each time the
-      command is run
+-  ``e`` uses environment variable **$SHELL** to guess which shell is in use
+-  ``e`` redirects stderr to stdout and always returns an exit status of 0
+-  ``e`` uses *interactive shell* and this has pros and cons:
+
+   -  The user has access to all linux functions and aliases
+   -  The shell runtime configuration must be "sourced" each execution
    -  The performance of ``e`` is affected by the shell startup time
       (beware oh-my-zsh users)
    -  Any errors thrown during the "sourcing" will show up in the output
-      of ``e``
 
 -  ``dtags edit`` uses environment variable **$EDITOR**
--  ``d`` prefers tags over subdirectories if there is a name conflict
-   -  To go to the subdirectory put a ``/`` after the directory name
--  ``d`` requires ``grep``, ``cut``, ``seq`` and ``/dev/null``
+-  ``d`` prefers tags over subdirectories when there are name conflicts
+
+   -  To go to the subdirectory, put a ``/`` after the directory name
+
 -  ``d`` expects ``~/.dtags/mapping`` to be correctly formatted:
 
-   -  Please refrain from editing ``~/.dtags/mapping`` directly
+   -  Please refrain from editing ``~/.dtags/mapping`` directly.
    -  Instead, use ``dtags edit`` which does the validation and
       formatting for you
 
@@ -149,3 +140,5 @@ Technical Notes
    -  Don't touch this file at all if possible
    -  If this is deleted, it is auto-generated the next time a dtags
       command is run.
+-  For a shell variable to be created automatically, the tag name must
+   not conflict with environment variable names 

dtags/chars.py

@@ -6,7 +6,7 @@
     'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', 'A', 'B', 'C', 'D',
     'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S',
     'T', 'U', 'V', 'W', 'X', 'Y', 'Z', '0', '1', '2', '3', '4', '5', '6', '7',
-    '8', '9', '-', '_', '.'
+    '8', '9', '_',
 }
 # Allowed characters in directory paths
 PATH_CHARS = {