Skip to content

Commit

Permalink
Merge pull request #2 from andrewpmartinez/release-0.3.0
Browse files Browse the repository at this point in the history 
Release 0.3.0
  • Loading branch information
@andrewpmartinez
andrewpmartinez authored Aug 24, 2020
2 parents d14466e + c375ac5 commit f1ea4fc
Show file tree
Hide file tree
Showing 6 changed files with 469 additions and 46 deletions.
234 changes: 197 additions & 37 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,79 @@
# ziti-git
A tool to manage multiple repositories with special considerations for the github.com/openziti project

A tool to manage multiple repositories with special considerations for
the github.com/openziti project

## Requirements

- git >= 1.14

## Installation

```
go get -u github.com/andrewpmartinez/ziti-git
go install github.com/andrewpmartinez/ziti-git
```

## Alias to `zg`

```
echo 'alias zg=$GOPATH/bin/ziti-git' >> ~/.bashrc
```

## Aliases

Most ziti-git commands have short aliases. Setting up `ziti-git` as the
alias `zg` and using the command aliases can shorten the typing
necessary for repetitive tasks.

#### Example w/o aliases:

```
> ziti-git table-status
```

#### Example w/ aliases:

```
> zg ts
```

Here is a list of some of the aliases:

```
b = branch
c = clone
l = list
r = register
ts = table-status
u = unregister
ut = unregister-tag
ul = use-local
```

Aliases can be found by use the `-h` flag on commands in the "Aliases"
section:

```
> ziti-git register -h
add the repo in <path> to the list of repos, with an optional <tag>
Usage:
ziti-git register [-t <tag>] <path> [flags]
Aliases:
register, r
Flags:
-h, --help help for register
Global Flags:
-t, --tag string limits actions to repos with <tag>
```


## Usage

```
Ziti Git is a multi-repo git tool with additions for the open ziti project!
Expand All @@ -25,13 +83,15 @@ Usage:
Available Commands:
branch list all repo branches or repos in <tag>
checkout inspects the go.mod file of the openziti/ziti repo to produce a script to checkout exact openziti dependencies necessary
clone clones the core openziti repos to the current directory
help Help about any command
list list all repos or repos for <tag>
register add the repo in <path> to the list of repos, with an optional <tag>
table-status show the table status of all the repos or of a specific tag
unregister unregister <repo>
unregister-tag unregister-tag <tag>
use-local alter go.mod files for ziti repos to use local repositories via replace directives
Flags:
-h, --help help for ziti-git
Expand All @@ -40,29 +100,53 @@ Flags:
Use "ziti-git [command] --help" for more information about a command.
```

## Getting Started
## Cloning -- Getting Started With Ziti

To start hacking away on Ziti first clone the `github.com/openziti/ziti`
repositories. It is suggested to run the `ziti-git clone` command inside
an empty directory as multiple directories will be created.

To start hacking away on Ziti first clone the repos:
Example:

```
mkdir ziti
cd ziti
ziti-git clone
```

If you want to add these new repos to ziti-gits repo list use the `-r` flag
and optionally the `-t` flag to set a specific tag.
For easier management later, it is useful to register the cloned
repositories with `ziti-git` and specify a tag. This will make it easier
to manipulate them individually with the `-t` flag that is available on
most `ziti-git` commands.

```
mkdir ziti
cd ziti
ziti-git clone -r -t myTag
ziti-git clone -r -t myZiti
```

You can clone then build to get your own copy of Ziti built and ready
for use:

```
mkdir myziti
cd myziti
ziti-git clone -r -t myZiti
cd ziti
go build ./...
```

The above will checkout the necessary Ziti repositories and then build
the Ziti binaries. They will end up `~/go/bin` or to the environment
variable path defined by `GOBIN` if set. The repository in the `ziti`
folder will contain the `openziti/ziti` repository which holds the code
that will build all of openziti's binaries.

## Table Status

A tabular Git status can be displayed by using the `table-status` or `ts` command. The output
can be limited by specifying a specific tag via `-t`.
A tabular Git status can be displayed by using the `table-status` or
`ts` command. The output can be limited by specifying a specific tag via
`-t`.

```
> ziti-git table-status
Expand All @@ -76,11 +160,11 @@ can be limited by specifying a specific tag via `-t`.
+------------+--------------+----------+--------+----------+-------------------------------------------+
```

## Fetching On All Repos
## Fetching On All Repositories

Arbitrary git command can be executed on the entire set of repos or
sets defined by tags. In this example `git fetch` will be executed on
all repos.
Arbitrary `git` command can be executed on the entire set of
repositories or sets defined by tags. In this example `git fetch` will
be executed on all repositories.

```
> ziti-git fetch
Expand All @@ -92,10 +176,10 @@ Or on a specific tag:
> ziti-git -t myTag fetch
```

This can also be used to create branches, checkout branches, hard
reset, etc. across all repos.
This can also be used to create branches, checkout branches, hard reset,
etc. across all repositories.

## Unregister Repo
## Unregistering Repositories

Repositories can be removed by location or by tag. To remove a specific
repository by path:
Expand All @@ -105,46 +189,122 @@ repository by path:
```

To remove all repositories with a specific tag:

```
> ziti-git unregister-tag myTag
```

## Aliases
## Using Local -- Local Development

By default, building against the `openziti/ziti` repository folder
`ziti` will use its `go.mod` file to look up the correct versions to
build. If you would like to use only the locally checked out versions
(useful for developing locally) the `ziti-git use-local` command is
useful to update the `go.mod` file to add `replace` directives to use
your locally checked out versions.

The command makes the following assumptions:

Most ziti-git commands have short aliases:
- it is being run in the directory containing the `openziti/*`
repositories
- it assumes that the `ziti`, `foundation`, `edge`, and `fabric` folders
are siblings in said folder

```
b = branch
c = clone
l = list
r = register
ts = table-status
u = unregister
ut = unregister-tag
> ziti-git use-local
```

Using the `use-local` command will alter the `go.mod` file across some
or all of the repositories mentioned above (depending on usage).
Committing modified `go.mod` files with `replace` directives is
generally not advised unless it is for your own personal use.

To reverse this process use:

```
> ziti-git use-local --undo
```

Aliases can be found by use the `-h` flag on commands in the "Aliases" section:
To limit the scope of `use-local` the `-here` flag can be used within a
specific repository folder to alter only the `go.mod` folder of that
repository.

```
> ziti-git register -h
add the repo in <path> to the list of repos, with an optional <tag>
> cd edge
> ziti-git use-local --current
```

Usage:
ziti-git register [-t <tag>] <path> [flags]
`-here` can also be combined with `-undo` to limit the undo to only the
current repository.

Aliases:
register, r
```
> cd edge
> ziti-git use-local --current
> ziti-git use-local --current --undo
```

Flags:
-h, --help help for register
Specific repositories can also be swapped to use the locally checked out
versions by specifying them via the `--repo` flag.

Global Flags:
-t, --tag string limits actions to repos with <tag>
The following would only use the local `edge` repository.

```
> ziti-git use-local --repo .*?edge.*?
```

Note that the repo flag treats the input as a regular expression. If
your shell requires escape characters (i.e. bash and `\`) those must be
applied on top of any regular expression escaping necessary.

The `--repo` flag can also be combined with `--current` and `--undo`. It
may also be specified multiple times.

### Checking Out Exact Matching Versions

When debugging issues or recreating historical versions, it is useful to
checkout the exact repository commits that were used to build a specific
version. The `ziti-git checkout` command can do that for you.

If you wish to checkout the commits used to build the `v0.16.0` of Ziti,
you can do the following:

```
> mkdir ziti-0.16.0
> cd ziti-0.16.0
> ziti-git clone -r -t v0.16.0
> cd ziti
> git checkout v0.16.0
> ziti-git checkout
```

Would output:

```
cd "/home/user/repos/ziti-0.16.0"
git -C "./edge" checkout v0.15.40
git -C "./fabric" checkout v0.12.1
git -C "./foundation" checkout v0.12.0
git -C "./sdk-golang" checkout v0.13.30
```

That output can be executed to checkout the proper versions. After that
the `use-local` command can be used to work on that specific version of
the openziti project - potentially to work on bug fix!

These repositories can then later be removed from `ziti-git` as the
`v0.16.0` tag was used when they were cloned and registered during the
`clone` command (i.e. `-r -t v0.16.0`)

```
> ziti-git unregister-tag v0.16.0
> rm -rf ./ziti-0.16.0/*
```

## Prior Art

## Acknowledgements
Ziti Git is based off of [gmg](https://github.com/abrochard/go-many-git) which in turn was inspired by the amazing [mr](https://myrepos.branchable.com) and [gr](https://github.com/mixu/gr) tools.
Ziti Git is based off of [gmg](https://github.com/abrochard/go-many-git)
which in turn was inspired by the amazing
[mr](https://myrepos.branchable.com) and
[gr](https://github.com/mixu/gr) tools.

A big thanks to all.
Loading

0 comments on commit f1ea4fc

Please sign in to comment.