git-project-manager/README.md

# Git Project Manager

## Purpose

The goal of this utility is to provide a fuzzy-find method of locating, cloning,
and using Git projects -- along with your preferred aliases, autocompletion,
and shortcuts.

This supports GitHub, GitLab, and Gitea remotes.

## Installation

Install git-project-manager using `go`:
`go install -v gitea.libretechconsulting.com/rmcguire/git-project-manager@latest`

OR Download a pre-built binary:
[https://gitea.libretechconsulting.com/rmcguire/-/packages/generic/git-project-manager](https://gitea.libretechconsulting.com/rmcguire/-/packages/generic/git-project-manager)

## Setup

**Generate a new config file:**
`git-project-manager config generate --write`

**For handy aliases and shell helpers:**
- Download `https://gitea.libretechconsulting.com/rmcguire/git-project-manager/raw/branch/main/contrib/gpm_func_omz.zsh`
- Implement however you like (e.g. copy to ~/.oh-my-zsh/custom/)

For just completion only, source completions from git-project-manager (e.g. for zsh, `source <(git-project-manager completion zsh)`)

_The following commands assume you've loaded the gpm alias and help funcs._

**Index your git repos**
`gpm cache load`

**Add your first project**
`padd` (gpm project add)

**Go to your project, fuzzily**
`pgo`

## Documentation

[Full documentation is available in docs/](./docs/git-project-manager.md)

## Functionality

This program will try like hell to help you fuzzily find a project,
and once you've found it, will remember your preference along with whatever crazy
thing your lizard brain wants to call it.

Do you think of a project called terraform as infra-stuff? No problem, just let
gpm know that and it'll remember.

The basic workflow looks like this:

1. **Config** -- generate a config file
1. **Cache** -- load your cache to make things super quick
	1. you only need to update it if there are new projects the cache is unaware of
1. **Add** -- find your project, give it any extra aliases you want
	1. run `gpm project add` (or `padd` if using the provided shell defaults)
1. **Go** -- go to your project, fuzzy searching by alias
	1. clones your project if that's never been done
	1. the provided `pgo` func makes it easy
1. **Open** -- rather than simply changing directories to a project, open it in your IDE
1. **Manage** -- fine-tune your aliases, making it easy to nail them without fuzzy stuff
	1. if you are lazy in your aliases, you'll be fuzzy finding a lot
	1. match your alias exactly (or have only one result) and you go there right away
	1. positive reinforcement given for solid alias behavior
	1. manage aliases using `gpm alias add` or `gpm alias delete`
1. **List** -- get a list of your configured projects any time with `plist`
1. **Reward** -- buy the author a beer, because this thing is a time saver

### Config Sample
```yaml
remotes:
  - host: https://github.com/rdmcguire # add user for multiple keys
    token: <your token here>
    name: github-rdmcguire
    type: "github" # github, gitlab, gitea supported
    cloneProto: ssh
logLevel: info
cache:
  ttl: 168h
  load:
    ownerOnly: false # if true, only owned projects will be indexed
```
## Usage

### Global Flags

- The `--remote` flag limits all subcommands to one or more specified remotes
- The `--logLevel [debug|error|info|warn]` flag sets logging, but is permanent in the config file

### Basic Usage

Basic usage to prepare your cache, add a project alias (or aliases), and use a project:

1. `gpm cache load`
1. `gpm project add`
  1. select with fuzzy search, add extra aliases if preferred
1. `gpm project [go|open] <optional-fuzzy-search-term>`
  1. Open will launch your editor, go will change directories, cloning if necessary

### Cache Management

```shell
% git-project-manager cache -h
Contains sub-commands for managing project cache.
The project cache keeps this speedy, without smashing against the Git remote's
API every time a new project is added / searched for

Usage:
  git-project-manager cache [command]

Aliases:
  cache, a, ln

Available Commands:
  clear       Clear Git Project Cache
  dump        Dump Git project cache
  load        Load Git Project Cache
  unlock      unlock Git project cache

Flags:
  -h, --help           help for cache
      --ttl duration   Duration before cache is re-built in go time.Duration format (default 48h0m0s)

Global Flags:
      --config string        config file (default is ~/.config/git-project-manager.yaml)
      --logLevel string      Default log level -- info, warn, error, debug (default "info")
      --projectPath string   Sets a path for local clones of projects
      --remote strings       Specify remotes by host for any sub-command. Provide multiple times or comma delimited.

Use "git-project-manager cache [command] --help" for more information about a command.
```

- To update your cache, run `gpm cache load`. You can also specify one or more remotes
  with `--remote [host]` either multiple times or comma delimited. Command completion works.
- To view basic cache stats, run `gpm cache dump`
- To dump cache projects and any aliases that are set, run `gpm cache dump -f` optionally filtering with `--remote` flags

## TODO

- [x] Don't check remote up unless necessary (project list shouldn't require it)
- [x] Rename to git-project-manager
- [x] Move module to github.com/rdmcguire
- [ ] Add flag for clone timeout for large repos
- [ ] Add `gpm cache prune` command
- [ ] Fix NPE when cache is reset or project for whatever reason leaves an orphaned alias
- [ ] Add TTL check to cache load, and add -f / --force flag to re-build regardless
- [ ] Update README for shell completion, aliases, usage
- [ ] Make a Makefile
- [ ] Add git repo status to project go (up-to-date, pending commits, etc..)
- [ ] Build pipeline, and link to registry for a release binary
- [ ] Add GitHub remote
- [ ] Package for homebrew
- [x] Make generic, this is any git remote, not just GitLab
    - [x] Add Gitea support
    - [x] Add GitHub support
    - [x] Remove separate gitlab/gitea logic and keys, stop supporting legacy keys
    - [x] Rename --gitlab flag to --remote
- [x] Add option to select individual remote for `gpm cache load`
- [x] Use multi-gitlab by default in config init
    - [x] Update docs for multi-gitlab
    - [x] Remove all references to old keys
    - [x] Add auto-completion helper for --gitlab flag
- [x] Fix initial setup requiring project path, and set https:// as default for gitlab host
- [x] Add config setters and getters
- [x] For each project loaded, check if it is the same, and do nothing
	- [x] prevents clobbering cache on a partial update
	- [x] track already loaded projects to diff after load
- [x] Add open command
	- [x] config should exist for editor (vim, code, etc..)
- [x] Add fzf to `plist` / `gpm projects list`
- [x] Update `gpm project show` with pterm box like `gpm project list`
- [x] Merge aliases together for same project when selecting
	- [x] If after merging there is only one project, go there by default