https://github.com/cloud-native-toolkit/git-client
Client to interact with different Git server apis
https://github.com/cloud-native-toolkit/git-client
Last synced: 4 months ago
JSON representation
Client to interact with different Git server apis
- Host: GitHub
- URL: https://github.com/cloud-native-toolkit/git-client
- Owner: cloud-native-toolkit
- Created: 2021-11-16T06:16:35.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2023-07-05T18:12:23.000Z (almost 3 years ago)
- Last Synced: 2025-10-22T05:49:20.907Z (8 months ago)
- Language: TypeScript
- Size: 1.53 MB
- Stars: 0
- Watchers: 4
- Forks: 1
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Git client
SDK to interact with different git servers using a consistent api.
## CLI installation
To install the latest version of gitu into `/usr/local/bin`, run the following:
```shell
curl -sL https://gitu.cloudnativetoolkit.dev/install.sh | sh
```
If you would like to install the CLI in a different directory, use the following:
```shell
curl -sL https://gitu.cloudnativetoolkit.dev/install.sh | DEST_DIR=~/bin sh
```
## Usage
The SDK will determine the type of repo given the url to the server and return a `GitApi` instance that implements the apis for that server. The url can point to a specific repository or to an organization.
The api can be loaded using the `apiFromUrl` helper function:
```javascript
import {apiFromUrl} from 'git-client'
const api: GitApi = apiFromUrl('https://github.com/org/repo', {username, password})
```
From there, any of the implemented apis can be called. For example:
```javascript
api.createWebhook({webhookUrl: 'https://webhook'})
```
### Provided CLI commands
#### create
Creates a git repo from the provided information
```shell
export GIT_USERNAME="myuser"
export GIT_TOKEN="xxx"
gitu create my-repo -h github.com
```
To create the repo in a different org, include the `-o` flag
```shell
export GIT_USERNAME="myuser"
export GIT_TOKEN="xxx"
gitu create my-repo -h github.com -o myorg
```
#### exists
Checks if a given repo exists and return some information about it.
```shell
export GIT_USERNAME="myuser"
export GIT_TOKEN="xxx"
gitu exists https://github.com/myuser/my-repo
```
or you can check for the repo using the parts of the url
```shell
export GIT_USERNAME="myuser"
export GIT_TOKEN="xxx"
gitu exists my-repo -h github.com
```
#### delete
Deletes the provided repo
```shell
export GIT_USERNAME="myuser"
export GIT_TOKEN="xxx"
gitu delete https://github.com/myuser/my-repo
```
or you can delete the repo using the parts of the url
```shell
export GIT_USERNAME="myuser"
export GIT_TOKEN="xxx"
gitu delete my-repo -h github.com
```
#### clone
Clones the repository, handling the credentials and the name and email config
```shell
export GIT_USERNAME="myuser"
export GIT_TOKEN="xxx"
gitu clone https://github.com/myuser/my-repo
```
or you can clone the repo using the parts of the url
```shell
export GIT_USERNAME="myuser"
export GIT_TOKEN="xxx"
gitu clone my-repo -h github.com
```
### Provided APIs
The exposed APIs are defined in `lib/git.api.ts` in the `GitApi` abstract class. The available API functions are:
- `createRepo()` - creates a repository in the org
- `deleteRepo()` - deletes the repository
- `getWebhooks()` - list the defined webhooks
- `createWebhook()` - create a webhook on the repository
- `deleteBranch()` - deletes a branch in the repository
- `rebaseBranch()` - rebases a branch on top of another one in the repository
- `getPullRequest()` - retrieves a pull request from the repository
- `createPullRequest()` - creates a pull request in the repository for a given branch
- `mergePullRequest()` - merges the given pull request
- `updateAndMergePullRequest()` - updates the pull request with the latest from the target branch and merges it
- `updatePullRequestBranch()` - updates the pull request with the latest from the target branch
- `clone()` - clones the repository to the local file system
### Command-line credentials
Credentials can be provided to the command-line for each command using the `-u` and `--token` argument OR the credentials can be stored in a configuration file for each host.
The configuration file is named `.gitu-config` and should be stored in the home directory. Each entry should contain the `host`, `username` and `token`. Optionally, if the git server uses a self-signed certificate it can also be provided to the configuration with the `caCert` value.
For example:
```yaml
credentials:
- host: github.com
username: myuser
token: token
- host: git.myhost.com
username: githuser
token: token
caCert: /path/to/ca.crt
```
## Testing
The repository provides unit tests and integration tests. The unit tests can be run independently of any Git hosts. The integration tests require configuration, including credentials, in order to run.
### Unit tests
To execute the unit tests, run the following:
```shell
npm test
```
### Integration tests
The integration test runner will execute any files that match the pattern `*.ispec.ts`. To run the integration tests:
1. Copy `.env.template` to `.env` and provide values for the environment variables for the repositories you want to test. If environment variables are missing for a type of repository then it will be skipped (or you can skip testing a type of repository by setting XXX_SKIP="true")
2. Run the following command:
```shell
npm run test:integration
```
**Note:** The integration tests will create a repository, execute some APIs, then delete the repository. The Personal Access Token provided for the `XXX_PASSWORD` environment variable needs to have enough permission to delete the repo.
## Notes
- clone {url} [{path}] (include name and email config)
- pr create
- pr merge
- pr get