mirror of
https://github.com/grdl/git-get.git
synced 2026-02-05 03:49:42 +00:00
Add more documentation to readme
This commit is contained in:
Grzegorz Dlugoszewski
152
README.md
152
README.md
@@ -7,7 +7,7 @@
|
||||
`git-get` is a better way to clone, organize and manage multiple git repositories.
|
||||
|
||||
It gives you two new git commands:
|
||||
- **`git get`** clones repositories into an automatically created directory tree based on repo's URL (like golang's [`go get`](https://golang.org/cmd/go/)). It's dotfiles friendly, you can clone multiple repositories listed in a file.
|
||||
- **`git get`** clones repositories into an automatically created directory tree based on repo's URL (like golang's [`go get`](https://golang.org/cmd/go/)). It's dotfiles friendly, meaning you can also give it a file with a list of repositories and it will clone all of them.
|
||||
- **`git list`** shows status of all your git repositories and their branches.
|
||||
|
||||
|
||||
@@ -15,39 +15,175 @@ It gives you two new git commands:
|
||||
|
||||
## Installation
|
||||
|
||||
Using Homebrew:
|
||||
Use Homebrew:
|
||||
```
|
||||
brew install grdl/tap/git-get
|
||||
```
|
||||
|
||||
Or grab the [latest release](https://github.com/grdl/git-get/releases) and put the binaries on your PATH.
|
||||
|
||||
Each release contains two binaries: `git-get` and `git-list`. When put on PATH, git automatically recognizes them as custom commands and allows to call them as `git get` or `git list`.
|
||||
Each release contains two binaries: `git-get` and `git-list`. When put on PATH, git automatically recognizes them as custom commands and allows to run them as `git get` or `git list`.
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
### git get
|
||||
```
|
||||
git get <REPO> [flags]
|
||||
|
||||
Flags:
|
||||
-b, --branch string Branch (or tag) to checkout after cloning. Tag name needs to be prefixed with 'refs/tags/'. (default "master")
|
||||
-d, --dump string Path to a dump file listing repos to clone. Ignored when <REPO> argument is used.
|
||||
-h, --help Print this help and exit.
|
||||
-t, --host string Host to use when <REPO> doesn't have a specified host. (default "github.com")
|
||||
-p, --privateKey string Path to SSH private key. (default "~/.ssh/id_rsa")
|
||||
-r, --root string Path to repos root where repositories are cloned. (default "~/repositories")
|
||||
-v, --version Print version and exit.
|
||||
```
|
||||
|
||||
The `<REPO>` argument can be any valid URL supported by git. Such as:
|
||||
```
|
||||
https://github.com/grdl/git-get
|
||||
git@github.com:grdl/git-get.git
|
||||
ssh://user@server/repository.git
|
||||
file:///project/repository.git
|
||||
```
|
||||
|
||||
#### Short URLs
|
||||
|
||||
`<REPO>` can be a short path without any protocol or host. In that case `git-get` will automatically use the `https` protocol and the configured host (github.com by default).
|
||||
For example `git get grdl/git-get` will clone `https://github.com/grdl/git-get.git`.
|
||||
|
||||
#### Dump file
|
||||
|
||||
`git get` is dotfiles friendly. Using `--dump` flag, it accepts a file with a list of repositories and clones all of them.
|
||||
|
||||
Dump file format is simply:
|
||||
- Each repo URL on a separate line.
|
||||
- Each URL can have a suffix with a branch or tag name to check out after cloning. If that suffix is missing, `master` will be used.
|
||||
- Tag name should be prefixed with `refs/tags/`.
|
||||
|
||||
Example dump file contents:
|
||||
```
|
||||
https://github.com/grdl/git-get refs/tags/v1.0.0
|
||||
git@github.com:grdl/another-repository.git
|
||||
```
|
||||
|
||||
You can generate a dump file with all your currently cloned repos by running:
|
||||
```
|
||||
git list --out dump > repos.dump
|
||||
```
|
||||
|
||||
|
||||
### git list
|
||||
```
|
||||
Usage:
|
||||
git list [flags]
|
||||
|
||||
Flags:
|
||||
-f, --fetch First fetch from remotes before listing repositories.
|
||||
-h, --help Print this help and exit.
|
||||
-o, --out string Output format. Allowed values: [dump, flat, smart, tree]. (default "tree")
|
||||
-p, --privateKey string Path to SSH private key. (default "~/.ssh/id_rsa")
|
||||
-r, --root string Path to repos root where repositories are cloned. (default "~/repositories")
|
||||
-v, --version Print version and exit.
|
||||
```
|
||||
|
||||
`git list` provides different ways to view the list of the repositories and their statuses.
|
||||
|
||||
- **tree** (default) - rendered as a directory tree.
|
||||
```
|
||||
❯ git list
|
||||
/home/grdl/repositories
|
||||
└── github.com
|
||||
└── grdl
|
||||
├── git-get master 1 ahead [ untracked ]
|
||||
│ └── development ok
|
||||
├── homebrew-tap master ok
|
||||
└── testsite master ok
|
||||
```
|
||||
|
||||
- **flat** - each repo (and each branch) on a new line with full path to the repo.
|
||||
```
|
||||
❯ git list -o flat
|
||||
/home/grdl/repositories/github.com/grdl/git-get master 1 ahead [ untracked ]
|
||||
development ok
|
||||
/home/grdl/repositories/github.com/grdl/homebrew-tap master ok
|
||||
/home/grdl/repositories/github.com/grdl/testsite master ok
|
||||
```
|
||||
|
||||
- **dump** - each repo URL with current branch on a new line. Accepted by `git get --dump` command.
|
||||
```
|
||||
❯ git list -o dump
|
||||
https://github.com/grdl/git-get.git master
|
||||
https://github.com/grdl/homebrew-tap master
|
||||
https://github.com/grdl/testsite master
|
||||
```
|
||||
|
||||
- **smart** (experimental) - similar to the tree view but saves space by automatically folding paths with only a single child.
|
||||
```
|
||||
❯ git list -o smart
|
||||
/home/grdl/repositories
|
||||
github.com/grdl/
|
||||
git-get master 1 ahead [ untracked ]
|
||||
development ok
|
||||
homebrew-tap master ok
|
||||
testsite master ok
|
||||
```
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
Each configuration flag listed in the [Usage](#Usage) section can be also specified using environment variables or .gitconfig file.
|
||||
|
||||
## Features
|
||||
The order of precedence for configuration is as follows:
|
||||
- command line flag (have the highest precedence)
|
||||
- environment variable
|
||||
- .gitconfig entry
|
||||
- default value
|
||||
|
||||
- statuses
|
||||
- multiple outputs
|
||||
- dotfiles friendly
|
||||
> **IMPORTANT!**
|
||||
>
|
||||
> When changing repos root path using .gitconfig or an env variable use a full, absolute path. For example, use `/home/greg/my_repos` instead of `~/my_repos` or `$HOME/my_repos`. This is becase `git-get` can't expand shell variables.
|
||||
|
||||
|
||||
### Env variables
|
||||
|
||||
Use the `GITGET_` prefix and the uppercase flag name to set the configuration using env variables.
|
||||
|
||||
For example, to use a different repos root path run:
|
||||
```
|
||||
export GITGET_ROOT=/path/to/my/repos
|
||||
```
|
||||
|
||||
### .gitconfig file
|
||||
|
||||
You can define a `[gitget]` section inside your `.gitconfig` file and set the configuration flags there. A common and recommended pattern is to set `root` and `host` variables there if you don't want to use the defaults.
|
||||
|
||||
Here's an example of a working snippet from `.gitconfig` file:
|
||||
```
|
||||
[gitget]
|
||||
root = /path/to/my/repos
|
||||
host = git.example.com
|
||||
```
|
||||
|
||||
`git-get` looks for the `.gitconfig` file in the following locations:
|
||||
- `XDG_CONFIG_HOME/git/config`
|
||||
- `~/.gitconfig`
|
||||
- `~/.config/git/config`
|
||||
- `/etc/gitconfig`
|
||||
|
||||
|
||||
## Contributing
|
||||
|
||||
Pull requests are welcome. The project is still very much work in progress. Here's some of the missing features planned to be fixed soon:
|
||||
- improvements to the `git list` output
|
||||
- improvements to the `git list` output (feedback appreciated)
|
||||
- submodules status
|
||||
- info about stashes
|
||||
- better recognition of different repo states: conflict, merging, rebasing, cherry picking etc.
|
||||
- plenty of bugfixes and tests
|
||||
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
Inspired by:
|
||||
|
||||
Reference in New Issue
Block a user