# cdirs

**Repository Path**: caobinxin/cdirs

## Basic Information

- **Project Name**: cdirs
- **Description**: 快速切换目录
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: cdirs-dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-11-03
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

cdirs
==========================
cdirs 用于在目录间任意跳转,对庞大的项目工程效果显著。

- 支持标签目录，支持任意目录跳转到标签标记的目录
- 支持回退目录，快速返回到上级目录，摆脱多次“../../../..”
- 支持检索目录，支持往前检索和跳转目录
- 支持跳转目录，快速跳转到任意曾今去过的目录
- 所有命令均支持tab补全

******

### 　　　　　　　　　　　　Author: 广漠飘羽
### 　　　　　　　　　 E-mail: gmpy_tiger@163.com

******

## 目录
- [简介](#简介)
    - [命令集](#命令集)
    - [标签类型](#标签类型)
- [特点](#特点)
    - [开发中功能](#开发中功能)
- [快速安装](#快速安装)
    - [安装步骤](#安装步骤)
    - [卸载步骤](#卸载步骤)
- [快速开始](#快速开始)
	- [目录切换](#目录切换)
	- [快速标记](#快速标记)
	- [标签格式](#标签格式)
    - [操作标签](#操作目录)
- [标签变量](#标签变量)
- [标签目录](#标签目录)
    - [标签目录简介](#标签目录介绍)
    - [标签目录命令](#标签目录命令)
- [回退目录](#回退目录)
    - [回退目录简介](#回退目录介绍)
    - [回退目录命令](#回退目录命令)
- [检索目录](#检索目录)
    - [检索目录简介](#检索目录介绍)
    - [检索目录命令](#检索目录命令)
- [跳转目录](#跳转目录)
    - [跳转目录简介](#跳转目录介绍)
    - [跳转目录命令](#跳转目录命令)
- [FAQ](#faq)

---

## 简介
cdirs 用于在目录间任意跳转，解决Linux命令行切换目录繁琐的痛苦。  
cdirs 使用`shell script`语言编写,在BASH环境下测试。

### 命令集
cdirs 包含多条命令:

| 命令 | 用途 |
| :-- | :-- |
| `cd` | 等同于传统的cd命令 |
| [`cds`](#标签目录) | 设置标签目录 |S
| [`cdl`](#标签目录) | 罗列已有标签目录 |
| [`cdd`](#标签目录) | 删除已有标签目录 |
| [`cdb`](#回退目录) | 回退到上N级目录 |
| [`cdf`](#检索目录) | 往前检索目录 |
| [`cdj`](#跳转目录) | 跳转到任意当前Shell终端曾经去过的目录 |

### 标签类型
标签目录支持默认标签、全局标签和本地标签。

| 标签类型 | 特点 |
| :---: | :--- |
| [`默认标签`](#默认标签) | 在Bash初始化时加载，作为开机即可用的标签目录 |
| [`全局标签`](#全局标签) | 标签目录对全部Bash终端有效 |
| [`本地标签`](#本地标签) | 标签目录对只对当前Bash终端有效 |

## 特点

- 支持标签目录，支持从任意目录跳转到标签标记的目录
- 支持回退目录，快速返回到上级目录，摆脱多次“../../../..”
- 支持检索目录，支持往前检索和跳转目录
- 支持跳转目录，快速跳转到任意曾今去过的目录
- 所有命令均支持tab补全

### 开发中功能

- 支持拼音跳转中文目录
- 支持模糊匹配英文大小写

## 快速安装
### 安装步骤
#### 获取cdirs

```Bash
git clone https://github.com/gmpy/cdirs.git ~/cdirs
```

#### 安装

* 自动安装  

执行安装脚本:
```Bash
~/cdirs/install.sh
```

* 手动安装

在**~/.bashrc**中添加:`source ~/cdirs.sh`

### 卸载步骤

* 自动卸载

**自动卸载只适用于自动安装的cdirs**，执行卸载脚本:
```Bash
~/cdirs/install.sh --remove
```

* 手动卸载

在**~/.bashrc**中删除: `source ~/cdirs.sh`

## 快速开始
### 目录切换
#### 切换到标签目录

与传统的`cd`命令一致，尾随的是**标签名**，例如：

```Bash
cd <标签名>
```

操作示例如下：

```Bash
$ cd ,download			#假设<,download = ~/下载>，此时等效于<cd ~/下载>
```

#### 切换到回退目录

```Bash
cdb [回退级数|回退目录名]
```

操作示例如下：

```Bash
$ pwd
/home/gmpy/workspace/android/packages/apps/Camera/src/com/android/camera
$ cdb 2		#往回跳2级，等效于<cd ../..>
/home/gmpy/workspace/android/packages/apps/Camera/src/com
$ cdb apps		#支持tab补全，直接回退到名为apps的目录（若重名则罗列供用户选择）
/home/gmpy/workspace/android/packages/apps
$ cdb			#显示并选择所有有效的回退目录
Which one do you wand:
0: /home/gmpy/workspace/android/packages/apps
1: /home/gmpy/workspace/android/packages
2: /home/gmpy/workspace/android
3: /home/gmpy/workspace
4: /home/gmpy
5: /home
Your choice [default 0]: 2 		#此处通过交互选择编号2的目录
/home/gmpy/workspace/android
```

#### 切换到检索目录

```Bash
cdf [-t 检索深度] <目录名>
```

操作示例如下：

```Bash
$ pwd
/home/gmpy/workspace/android/packages/apps/Camera
$ cdf com		#在当前目录检索名为com的目录，寻找深度默认为3，并切换到寻找到的目录
/home/gmpy/workspace/android/packages/apps/Camera/src/com
```

#### 切换到跳转目录

```Bash
cdj <目录名>		#当前bash去过的任意目录名，支持tab补全
```

操作示例如下：

```Bash
$ pwd
/home/gmpy/workspace/android/packages/apps/Camera		#曾去过名为Camera的目录
$ cdb android		#切到其他目录以方便演示
/home/gmpy/workspace/android
$ cdj Camera		#跳转到名为Camera的目录，支持tab补全
/home/gmpy/workspace/android/packages/apps/Camera
```

### 快速标记

快速标记用于快速标记当前目录，在任何时候都可通过快速标记返回标记目录

快速标记(`cd ,`)类似于`cd -`，与`cd -`的差别在于：

** `cd -`只能回到上一个目录，而快速标记(`cd ,`)可在任何时候任何目录回到标记目录**

目前只支持1个快速标记目录，且只在当前Bash终端有效

快速标记常用于标记当前工作目录，临时跳转出去进行操作后，跳转回工作目录

通过以下命令标记：

```Bash
cds ,
```

通过以下命令跳转：

```Bash
cd ,
```

通过以下命令显示：

```Bash
cdl ,
```

通过以下命令删除：

```Bash
cdd ,
```

### 标签格式

逗号开头，后接字母开头的字母/数字和符号`-`组合的字串

```Bash
,[字母开头的字母或数字或字符-的组合子串]
eg.
	,root1-android
	,desktop
```

### 操作标签
#### 默认标签

默认标签在cdirs初始化时自动加载到本地标签，在打开Bash后可直接使用。

默认标签常用于**标记固定常用的目录**，例如标记Android SDK的根目录（等效于croot），例如标记中文目录（eg. ~/桌面、～/下载）

默认标签的配置文件位于：

```Bash
${HOME}/.cdirs-default
```

通过以下命令设置标签：

```Bash
cds -d <标签名> [目录路径]  		#若[目录路径]为空，则默认为当前目录
```

通过以下命令删除标签：

```Bash
cdd -d [标签名]
```

通过以下命令显示标签：

```Bash
cdl -d [标签名]
```

以标记Android SDK根目录和中文桌面目录为例

```Bash
$ cds -d ,root ~/workspace/project/andoid		#指定目录路径
$ cd ~/桌面		#切换目录，用于演示不指定目录路径情况
$ cds -d ,desktop		#不使用目录路径
```

标记后的默认标签文件：

```Bash
$ cat ~/.cdirs-default
,root = /home/gmpy/workspace/project/android
,desktop = /home/gmpy/桌面
```

#### 全局标签

cds设置的标签默认为全局标签。

全局标签**对系统内当前用户的所有Bash终端有效**，在重启后清空，对多终端的使用场景非常方便。

全局标签的优先级 < 本地标签的优先级，意味着**如果本地标签与全局标签同名，默认使用本地标签**。

通过以下命令设置标签：

```Bash
cds <标签名>
```

通过以下命令删除标签：

```Bash
cdd <标签名>
```

通过以下命令显示标签：

```Bash
cdl <标签名>		# [top]标示：在综合全局标签和本地标签后的有效标签 (本地标签优先级 > 全局标签优先级)
```

#### 本地标签

本地标签区别于全局标签，本地标签**只对当前Bash有效**，且本地标签优先级 > 全局标签优先级

通过以下命令设置标签：

```Bash
cds -l <标签名>
```

通过以下命令删除标签：

```Bash
cdd -l <标签名>
```

通过以下命令显示标签：

```Bash
cdl -l <标签名>			#[local]标示：显示的是本地标签
```

## 标签变量

标签目录支持变量，以支持根据不同方案动态改变标签标记的目录，对多个方案的SDK开发时切换目录特别高效

以Android SDK为例，在lunch方案后，会根据方案动态修改变量：OUT，根据此变量设置标签，可动态进入方案相关目录

```Bash
$ cds ,out '${OUT}'		#在Bash中务必用单引号括住变量，否则会被自动解析变量
```

也可以把变量定义在cdirs的配置文件中：

```Bash
${HOME}/.cdirsrc
```

此配置文件由shell语言组织，在cdirs初始化时，先加载此配置，再加载[默认标签](#默认标签)

使用示例：

```Bash
#<${HOME}/.cdirsrc>
ANDROID_TOP=/home/gmpy/workspace/Android

#<${HOME}/.cdirs-default
,root = ${ANDROID_TOP}
,package = ${ANDROID_TOP}/packages
```

## 切换目录
### 切换目录简介

切换目录主要为`cd`命令，是Bash内建命令`cd`的增强版，通过alias的形式替换内建`cd`。

当本地标签与全局标签具有同名标签目录时，`cd <标签>`默认会进入到本地标签，除非通过`-g`选项强制解析为全局标签。

当标签与本地文件夹重名，优先保证内建`cd`的功能，进入到重名的本地文件夹。

`cd`命令的使用参考[目录切换](#目录切换)，此处主要是介绍`cd`命令的选项。

### 切换目录命令
#### cd命令

```Bash
cd [选项]... [目录|标签|,]
```

- `cd [目录]`的使用于内建`cd`一致
- `cd [标签]`跳转到标签标记的目录
- `cd ，`跳转到快速标记的目录

| 选项 | 含义 |
| :--- | :--- |
| -h | 显示帮助信息 |
| -l | 跳转到本地标签标识的目录 |
| -g | 跳转到全局标签标识的目录 |
| --reset | 重新初始化cdirs |
| --reload | 重新加载默认标签 |

## 标签目录
### 标签目录简介

标签目录是通过设定标签的形式标记目录，可在任意时候任意目录通过标签跳转到标记的目录。

标签分为[默认标签](#默认标签)、[全局标签](#全局标签)、[本地标签](#本地标签)，三者的[作用范围](#标签类型)也不相同。

所有标签支持[环境变量](#标签变量)实现动态标记目录，对多个方案的SDK开发时切换目录特别高效。

标签的标记符号是逗号(`，`)，因此所有[标签格式](#标签格式)必须以逗号开头，以区分常规目录路径。

优先级： **本地标签 > 全局标签 > 默认标签** (默认标签只会在初始化cdirs时加载到本地标签)

### 标签目录命令
#### cds命令

```Bash
 cds [选项]... [,] <标签> [目录路径]
```

- cds 表示 cdirs set label，设置标签专用命令。
- 标签标记的**目录必须存在**，即使使用标签变量，在设置标签时会解析标签变量后检查目录是否存在
- 若无指定目录路径，则标记当前目录
- 默认在全局标签中标记目录，可通过`-l | -d`选项修改标记目录记录位置
- `cds ,`用于[快速标记](#快速标记)

| 选项 | 含义 |
| :-- | :-- |
| -h | 显示帮助信息 |
| -g | 记录在[全局标签](#全局标签) |
| -d | 记录在[默认标签](#默认标签) |
| -l | 记录在[本地标签](#本地标签) |
| -a | 等效于 -lgd |

#### cdl

```Bash
cdl [选项]... [,|标签]
```

- cdl 表示 cdirs list label，列出标签专用命令
- 如果不指定任何标签，则列出本地标签叠加全局标签后的有效（顶层）标签，用**[top]**标识
- [top]标识的标签目录可通过`cd <标签>`的形式直接使用
- cdl 通过 **[local]** 标识本地标签，通过 **[global]** 标识全局标签
- 可通过`-p`选项，把cdl内嵌到其他命令中，例如：

```Bash
$ cdl -p ,desktop
/home/gmpy/桌面
$ cp cdirs.sh `cdl -p ,udisk` 		#等效于 cp cdirs.sh /home/gmpy/桌面
```

| 选项 | 含义 |
| :--- | :--- |
| -h | 显示帮助信息 |
| -d | 显示默认标签 |
| -l | 显示本地标签 |
| -g | 显示全局标签 |
| -a | 等效于-lgd |
| -p <标签名> | 只显示路径，然后退出，用于内嵌到其他命令中 |

#### cdd

```Bash
cdd [选项]... [,|标签]
```

- cdd 表示 cdirs delete label，删除标签专用命令
- cdd 标签缺省时，则删除所有的标签，可通过`-d`,`-l`,`-g`指定删除的标签类型，缺省删除全局标签

| 选项 | 含义 |
| :--- | :--- |
| -h | 显示帮助信息 |
| -d | 从默认标签中删除 |
| -l | 从本地标签中删除 |
| -g | 从全局标签中删除 |
| -a | 等效于-lgd |

## 回退目录
### 回退目录简介

回退目录是返回上N级目录的快速方法，主要解决多次"../../.."的繁琐。

### 回退目录命令
#### cdb

```Bash
cdb [选项]... [目录名|回退级数]
```

- cdb 表示 cdirs back，回退上N级目录专用命令
- 目前支持两种回退形式，一个是指定回退目录名，一个是指定回退级数
- 回退目录名是`pwd`中的所有目录名，支持tab补全
- 回退级数是返回上级目录的次数，例如`cdb 2`等效于`cd ../..`
- 缺省时，会罗列出所有有效的回退目录，提供选择
- 在参数中优先识别为目录名，如果目录名无匹配，则识别为回退级数，可通过`-d`选项强制解析为回退级数

| 选项 | 含义 |
| :--- | :--- |
| -h | 显示帮助信息 |
| -d <回退级数> | 指定回退级数，当存在目录名与级数相同时使用 | 

## 检索目录
### 检索目录简介

检索目录通过调用find命令寻找并跳转到匹配的目录

### 检索目录命令

```Bash
cdf [选项]... [目录名]
```

- 目录名支持tab补全，但检索到目录较多时，补全时间较长
- 默认从当前目录检索，可通过`-t`选项修改检索的基础路径
- 默认检索深度是3，可通过`-d`选项修改检索深度
- 当出现多个匹配时，罗列出所有有效的检索目录，提供选择

| 选项 | 含义 |
| :--- | :--- |
| -h | 显示帮助信息 |
| -d <检索深度> | 修改本次检索深度 |
| -t <标签名> | 从指定标签名标记的路径中检索 |

## 跳转目录
### 跳转目录简介

跳转目录实现跳转到当前Bash终端曾经去过的任意目录

### 跳转目录命令

```Bash
cdj [选项]... <目录名>
```

- 目录名支持tab补全
- 缺省目录名时，等效于`cd .`
- 当出现多个重名匹配时，罗列出所有有效的跳转目录，提供选择（顺序排名越小，使用时间间隔越短，即0选项为最近去过的匹配的目录）

| 选项 | 含义 |
| :--- | :--- |
| -h | 显示帮助信息 |

## FAQ
### 1. 明明有设定标签,为什么`cd <,标签>`会进入到其他文件夹？

cdirs会优先确保cd功能,当前目录若存在与标签同名文件夹,会优先进入同名文件夹而非标签目录

可以通过`-l|-g`参数强制指定进入标签目录

### 2. `cdl -p`嵌入到其他命令中为什么有时会失效？

当绑定的路径存在空格时，`cdl -p`会失效
例如:
```Bash
$ cdl -p ,work
/home/user/my work #此路径存在有空格的文件夹'my work'

$ ll `cdl -p ,work`/src    #等效于"ll /home/user/my work/src"，bash解析为"ll /home/user/my" ; "ll work/src"
```
可以通过添加双引号的方式解决：
```Bash
$ ll "`cdl -p ,work`"/src
```