Metadata-Version: 2.4
Name: pigit
Version: 1.8.7
Summary: Simple terminal tool of Git.
Author-email: Zachary Zhang <zlj19971222@outlook.com>
License: MIT License
        
        Copyright (c) 2021 Zachary
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/zlj-zz/pigit.git
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Shells
Classifier: Topic :: Software Development
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: plenty==1.0.2
Provides-Extra: dev
Requires-Dist: setuptools>=64; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: pyinstrument; extra == "dev"
Requires-Dist: requests; extra == "dev"
Dynamic: license-file

# PIGIT

![Python 3](https://img.shields.io/badge/Python-v3.9%5E-green?logo=python)
[![pypi_version](https://img.shields.io/pypi/v/pigit?label=pypi)](https://pypi.org/project/pigit)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

A terminal tool for git. Read as [Pi Git], meaning to use git like pig it. When we use git, do you feel very uncomfortable with too long commands. For example: `git status --short`, this project can help you improve it. This project is written in Python. Now most UNIX like systems come with Python. So you can easily install and use it.

## Usage

If you want to use it, you must first know what it can do.

The command of `pigit -h` or `pigit --help` to get the help message with usage. Like this:

```bash
usage: pigit [-h] [-i] [-f] [-r] [-v] [-c [PATH]] [--create-ignore TYPE]
             [--complete [SHELL]] [--create-config]
             {cmd,repo,open} ...

Pigit TUI is called automatically if no parameters are followed.


positional arguments:
  {cmd,repo,open}
    cmd                 git short command.
    repo                repos options.
    open                open remote repository in web browser.


options:
  -h, --help            show this help message and exit
  -i, --information     Show some information about the current git repository.
  -f, --config          Display the config of current git repository and exit.
  -r, --report          Report the pigit desc and exit.
  -v, --version         Show version and exit.


tools arguments:
  Auxiliary type commands.

  -c [PATH], --count [PATH]
                        Count the number of codes and output them in tabular form.
                        A given path can be accepted, and the default is the
                        current directory.
  --create-ignore TYPE  Create a demo .gitignore file. Need one argument, the type
                        of gitignore.
  --complete [SHELL]    Add shell prompt script and exit. (Supported bash, zsh,
                        fish)
  --create-config       Create a pre-configured file of PIGIT.(If a profile
                        exists, the values available in it are used)
```

### Interaction

Even if you can use short commands instead of long commands of git, there are still some cases where simple commands can be very bad. For example: `git add a/b/1.txt b/c/1.txt c/d/1.txt`.

Therefore, we need a TUI to help us, so Pigit provides a simple command-line interactive TUI. When you use `pigit` without following any parameters, you will enter it.

![interaction demo](./docs/resources/demo_interaction.gif)

And in the interaction mode, you can use `?` or `h` to see the help message.

### `cmd`

The command of `cmd` support some short sub-command to replace the long git original command.

![demo display](./docs/resources/demo.gif)

**Discovery**

- `pigit cmd -l` — full table of short commands, help text, and underlying `git` lines (same idea as the old list flag).
- `pigit cmd -s <query>` / `--search <query>` — case-insensitive substring filter over names, help, and command text.
- `pigit cmd -t` — print supported types; `pigit cmd -t Branch` (etc.) — commands in that type.
- `pigit cmd -p` / `--pick` — built-in interactive picker (TTY only): `j` / `k` move, `Enter` run, `/` then a line to filter, `q` quit, or type a number and `Enter`. If a command accepts arguments, you get a `pigit cmd <short> ` line and an empty-line prompt for extra args (then one run).

Use `pigit cmd -l` to check what short command it supported, it will display the corresponding help information and the git original command, like this:

```
These are short commands that can replace git operations:
    b        lists, creates, renames, and deletes branches.
             git branch
    bc       creates a new branch.
             git checkout -b
    bl       lists branches and their commits.
             git branch -vv
    bL       lists local and remote branches and their commits.
             git branch --all -vv
    bs       lists branches and their commits with ancestry graphs.
             git show-branch
    bS       lists local and remote branches and their commits with ancestry graphs.
             git show-branch --all
    bm       renames a branch.
             git branch --move
    bM       renames a branch even if the new branch name already exists.
             git branch --move --force
    bd       delete a local branch by name.
             git branch -d
......
```

### `repo`

The command of `repo` support operate multiple repos at the same time.

![demo display](./docs/resources/demo_repo_1.png)
![demo display](./docs/resources/demo_repo_2.png)
![demo display](./docs/resources/demo_repo_3.png)

Use `pigit repo -h` to get more help.

**`repo cd` / `repo cd --pick`**: With a managed repo name that exists in `repos.json`, `pigit repo cd <name>` jumps into that working tree (same as before). Use **`pigit repo cd --pick`** (`-p`) in a real terminal to open the built-in list picker (j/k, `/` filter, Enter to confirm, q/Esc to quit). If you pass a name that is not an exact key, the picker opens with the filter pre-filled so you can narrow the list. Scripts and CI should pass an explicit name or avoid `--pick`; the picker requires stdin and stdout to be TTYs. Details: `docs/technical_repo_cd_interactive.md`.

```
usage: pigit

 repo [-h] {add,rm,rename,ll,clear,cd,fetch,pull,push} ...


positional arguments:
  {add,rm,rename,ll,clear,cd,fetch,pull,push}
    add                 add repo(s).
    rm                  remove repo(s).
    rename              rename a repo.
    ll                  display summary of all repos.
    clear               clear the all repos.
    cd                  jump to a repo dir.
    fetch               fetch remote update for repo(s).
    pull                pull remote updates for repo(s).
    push                push the local updates for repo(s).


options:
  -h, --help            show this help message and exit
```

## Installation

### Pip

```bash
pip install -U pigit
```

### Source

```bash
git clone https://github.com/zlj-zz/pigit.git --depth=1
cd pigit
make install
# or
python setup.py install  # On windows
```

### Development (editable install)

Runtime and dev dependencies are declared in `pyproject.toml`. After cloning:

```bash
pip install -e ".[dev]"
```

This replaces the old flat `requirements.txt` list; `requirements.txt` now points at the same extra for compatibility with `pip install -r requirements.txt`.

## Completion

Provides a friendly command-line completion capability, injecting completion through the following methods.

Write it to your shell configuration file：

```sh
# ~/.zshrc

eval "$(pigit --complete zsh)"
```

Currently supports `bash`, `zsh` and `fish`.

If no shell is specified, it will try to automatically detect what shell you are using.

```sh
eval "$(pigit --complete)"
```

## Alias

Alias is good way to help you use _pigit_ faster . Open your shell profile and append:

```bash
if type pigit >/dev/null 2>&1; then
    alias pg="pigit"
    alias gr="pigit repo"
fi
```

Then, you can use `pg` to call `pigit`.

**Windows**

Check your *PowerShell* config, like this: `echo $profile`. Create it if the path not exist. Then open it, and input:

```ps
set-alias pg pigit
```

After completing the above preparations, restart your terminal. If it prompts that you cannot run the configuration, you can refer to the [official website address](https://learn.microsoft.com/zh-cn/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.4).

## Configuration

You can use `pigit --create-config` to create a template configuration at **pigit** home path.

On Linux or MacOS: `~/.config/pigit`

On windows should be: `C:\\User\\<your username>`

[here](./examples/pigit.toml) is a configuration template.

| section      | key               | type  | default                     | desc                                                                                                                        |
| ------------ | ----------------- | ----- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| [cmd]        | display           | bool  | True                        | Show original git command.                                                                                                  |
| [cmd]        | recommend         | bool  | True                        | Is it recommended to correct when entering wrong commands.                                                                  |
| [counter]    | use_gitignore     | bool  | True                        | Whether to use the ignore configuration of the `.gitignore` file.                                                           |
| [counter]    | show_invalid      | bool  | False                       | Whether show files that cannot be counted.                                                                                  |
| [counter]    | show_icon         | bool  | True                        | Whether show files icons. Font support required, like: 'Nerd Font'.                                                         |
| [counter]    | format            | str   | table                       | Output format of statistical results. Supported: [table, simple]                                                            |
| [info]       | git_config_format | str   | table                       | Git local config print format. Supported: [table, normal]                                                                   |
| [info]       | repo_include      | list  | ["remote", "branch", "log"] | Control which parts need to be displayed when viewing git repository information. Support: (path,remote,branch,log,summary) |
| [repo]       | auto_append       | bool  | True                        | Whether auto append path to repos.                                                                                          |
| [log]        | debug             | bool  | False                       | Whether run PIGIT in debug mode.                                                                                            |
| [log]        | output            | bool  | False                       | Whether output log in terminal.                                                                                             |

## Custom Commands

You can define custom aliases and scripts via a TOML configuration file at the **pigit** home directory.

### Configuration file

Create `pigit.cmds.toml` in your pigit home directory:

- Linux/macOS: `~/.config/pigit/pigit.cmds.toml`
- Windows: `%USERPROFILE%\pigit\pigit.cmds.toml`

### Aliases

```toml
[cmd_new.aliases]
mybl = "bl"
mylog = "log --oneline --graph"
```

### Scripts

Multi-step command scripts:

```toml
[cmd_new.scripts.myscript]
steps = ["status", "log --oneline"]
help = "Show status then log"
category = "script"
```

Concise form (for simple step lists):

```toml
[cmd_new.scripts]
quick-check = ["status", "diff --cached"]
```

In `pigit cmd -l`, search, and `--pick`, user-defined entries are prefixed with `[alias]` or `[script]` so you can tell them apart from built-ins.

## Feature

- Short command for quick use Git, and custom your short command.
- Provides command correction, when the command is wrong.
- Have a simple tui interaction, complete very troublesome operations.
- Code statistics and can be beautifully displayed.
- Support generate and use shell completion script.
- Support create `.gitignore` template from internet.
- Support quick open remote url on website.
- Support manage multi repos.
- Have log output and help message tips.

---

LICENSE: [MIT](./LICENSE)
