Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/dalance/ptags

A parallel universal-ctags wrapper for git repository
https://github.com/dalance/ptags

code-navigation ctags developer-tools rust universal-ctags

Last synced: 24 days ago
JSON representation

A parallel universal-ctags wrapper for git repository

Lists

README 

        
# ptags

A parallel [universal-ctags](https://ctags.io) wrapper for git repository



[![Actions Status](https://github.com/dalance/ptags/workflows/Regression/badge.svg)](https://github.com/dalance/ptags/actions)

[![Crates.io](https://img.shields.io/crates/v/ptags.svg)](https://crates.io/crates/ptags)

[![codecov](https://codecov.io/gh/dalance/ptags/branch/master/graph/badge.svg)](https://codecov.io/gh/dalance/ptags)



## Description



**ptags** is a [universal-ctags](https://ctags.io) wrapper to have the following features.

- Search git tracked files only ( `.gitignore` support )

- Call `ctags` command in parallel for acceleration

    - Up to x5 faster than universal-ctags



## Install



### Download binary



Download from [release page](https://github.com/dalance/ptags/releases/latest), and extract to the directory in PATH.



### Arch Linux



You can install from AUR.



- https://aur.archlinux.org/packages/ptags/

- https://aur.archlinux.org/packages/ptags-git/



If you use `yay`, you can install like below:



```

yay -S ptags       // latest tagged version

yay -S ptags-git   // current master of git repo

```



### Cargo



You can install by [cargo](https://crates.io).



```

cargo install ptags

```



## Requirement



**ptags** uses `ctags` and `git` command internally.

The tested version is below.



| Command   | Version                                               |

| --------- | ----------------------------------------------------- |

| `ctags`   | Universal Ctags 0.0.0(f9e6e3c1) / Exuberant Ctags 5.8 |

| `git`     | git version 2.14.2                                    |

| `git-lfs` | git-lfs/2.3.3                                         |



## Usage



```

ptags 0.1.12-pre

[email protected]

A parallel universal-ctags wrapper for git repository



USAGE:

    ptags [FLAGS] [OPTIONS] [--] [DIR]



FLAGS:

        --config               Generate configuration sample file

        --exclude-lfs          Exclude git-lfs tracked files

    -h, --help                 Prints help information

        --include-ignored      Include ignored files

        --include-submodule    Include submodule files

        --include-untracked    Include untracked files

    -s, --stat                 Show statistics

        --unsorted             Disable tags sort

        --validate-utf8        Validate UTF8 sequence of tag file

    -V, --version              Prints version information

    -v, --verbose              Verbose mode



OPTIONS:

        --bin-ctags            Path to ctags binary [default: ctags]

        --bin-git                Path to git binary [default: git]

        --completion          Generate shell completion file [possible values: bash, fish,

                                          zsh, powershell]

    -e, --exclude ...            Glob pattern of exclude file ( ex. --exclude '*.rs' )

    -c, --opt-ctags ...        Options passed to ctags

    -g, --opt-git ...            Options passed to git

        --opt-git-lfs ...    Options passed to git-lfs

    -f, --file                    Output filename ( filename '-' means output to stdout ) [default: tags]

    -t, --thread                  Number of threads [default: 8]



ARGS:

        Search directory [default: .]

```



You can pass options to `ctags` by`-c`/`--ctags_opt` option like below.



```

ptags -c --links=no -c --languages=Rust

```



Searched file types per options are below.

`--include-submodule` and `--include_untracked` are exclusive.

This is the restriction of `git ls-files`.

Any include/exclude options without the above combination can be used simultaneously.



| File type     | Default  | --exclude-lfs | --include-ignored | --include-submodule | --include-untracked |

| ------------- | -------- | ------------- | ----------------- | ------------------- | ------------------- |

| tracked       | o        | o             | o                 | o                   | o                   |

| untracked     | x        | x             | x                 | x                   | o                   |

| ignored       | x        | x             | o                 | x                   | x                   |

| lfs tracked   | o        | x             | o                 | o                   | o                   |

| in submodules | x        | x             | x                 | o                   | x                   |



You can override any default option by `~/.ptags.toml` like below.

The complete example of `~/.ptags.toml` can be generated by `--config` option.



```toml

thread = 16

bin_ctags = "ctags2"

bin_git = "git2"

```



## Benchmark



### Environment

- CPU: Ryzen Threadripper 1950X

- MEM: 128GB

- OS : CentOS 7.4.1708



### Data



| Name    | Repository                           | Revision     | Files  | Size[GB] |

| ------- | ------------------------------------ | ------------ | ------ | -------- |

| source0 | https://github.com/neovim/neovim     | f5b0f5e17    | 2370   | 0.1      |

| source1 | https://github.com/llvm-mirror/llvm  | ddf9edb4020  | 29670  | 1.2      |

| source2 | https://github.com/torvalds/linux    | 071e31e254e0 | 52998  | 2.2      |

| source3 | https://github.com/chromium/chromium | d79c68510b7e | 293205 | 13       |



### Result



**ptags** is up to x5 faster than universal-ctags.



| Command       | Version                         | source0         | source1         | source2          | source3         |

| ------------- | ------------------------------- | --------------- | --------------- | ---------------- | --------------- |

| `ctags -R`    | Universal Ctags 0.0.0(f9e6e3c1) | 0.41s ( x1 )    | 3.42s ( x1 )    | 23.64s ( x1 )    | 32.23 ( x1 )    |

| `ptags -t 16` | ptags 0.1.4                     | 0.13s ( x3.15 ) | 0.58s ( x5.90 ) | 4.24s  ( x5.58 ) | 7.27s ( x4.43 ) |