Skip to content

Commit a723c4c

Browse files
dana-yaishdana-yaish
authored
Merge pull request #137 from codecov/dana/read-me
Update README.md
2 parents 62abfb1 + d7d7aa6 commit a723c4c

File tree

1 file changed

+172
-33
lines changed

1 file changed

+172
-33
lines changed

‎README.md

+172-33
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,187 @@
1+
# CodecovCLI
2+
3+
[![codecov](https://codecov.io/gh/codecov/codecov-cli/branch/master/graph/badge.svg?token=jN0CICuA6Z)](https://codecov.io/gh/codecov/codecov-cli)
4+
5+
CodecovCLI is a new way for users to interact with Codecov directly from the user’s terminal or CI platform. Many Codecov features that require the user’s interference can be done via the codecovCLI. It saves commits, creates reports, uploads coverage and has many more amazing features.
6+
17
- [Installing](#installing)
2-
- [Running the upload command](#running-the-upload-command)
3-
- [Running other commands](#running-other-commands)
8+
- [Usage](#usage)
9+
- [Codecov-cli Commands](#codecov-cli-commands)
10+
- [create-commit](#create-commit)
11+
- [create-report](#create-report)
12+
- [do-upload](#do-upload)
13+
- [create-report-results](#create-report-results)
14+
- [get-report-results](#get-report-results)
15+
- [pr-base-picking](#pr-base-picking)
16+
- [How to upload to Codecov](#how-to-upload-to-codecov)
17+
- [How to Local upload](#how-to-local-upload)
418
- [Plugin System](#plugin-system)
5-
- [Development](#development)
19+
- [Contributions](#contributions)
620
- [Requirements](#requirements)
721
- [Guidelines](#guidelines)
822
- [Releases](#releases)
923

1024
# Installing
1125

12-
To install this package locally, you can run
26+
To use codecov-cli in your local machine, or your CI workflows, you need to install it
1327

14-
`python setup.py develop`
28+
`pip install codecov-cli`
1529

16-
If you are installing from somewhere else, you can add:
30+
The above command will download the latest version of Codecov-cli. If you wish to use a specific version, releases can be viewed [here]().
31+
You can also find Codecovcli [here](https://cli.codecov.io/) or in the [Github releases](https://github.com/codecov/codecov-cli/releases) where you can download the binary distributable files.
1732

33+
# Usage
34+
If the installation is successful, running `codecovcli --help` will output the available commands along with the different general options that can be used with them.
1835
```
19-
codecov-cli @ git+ssh://[email protected]/codecov/codecov-cli.git@commitsha
36+
Usage: codecovcli [OPTIONS] COMMAND [ARGS]...
2037
```
21-
22-
to its requirements file
23-
24-
# Running the upload command
25-
26-
To run the CLI, do:
27-
38+
Codecov-cli supports inputs from the user. These inputs, along with their descriptions and usage contexts, are listed in the table below:
39+
40+
| Input | Description | Usage |
41+
| :---: | :---: | :---: |
42+
| `--auto-load-params-from` | The CI/CD platform | Optional |
43+
| `--codecov-yml-path` | The path for your codecov.yml | Optional
44+
| `--enterprise-url` | Change the upload host (Enterprise use) | Optional
45+
| `--version` | Codecov-cli's version | Optional
46+
| `--verbose` or `-v` | Run the cli with verbose logging | Optional
47+
48+
# Codecov-cli Commands
49+
| Command | Description |
50+
| :---: | :---: |
51+
| `create-commit` | Saves the commit's metadata in codecov, only need to do it once for a commit
52+
| `create-report` | Creates an empty report in codecov with initial data e.g. report name, report's commit
53+
| `do-upload` | Searches for and uploads coverage data to codecov
54+
| `create-report-results` | Used for local upload. It tells codecov that you finished local uploading and want it to calculate the results for you to get them locally.
55+
| `get-report-results` | Used for local upload. It asks codecov to provide you the report results you calculated with the previous command.
56+
| `pr-base-picking` | Tells codecov that you want to explicitly define a base for your PR
57+
58+
>**Note**: Every command has its own different options that will be mentioned later in this doc. Codecov will try to load these options from your CI environment variables, if not, it will try to load them from git, if not found, you may need to add them manually.
59+
60+
61+
62+
## create-commit
63+
`codecovcli create-commit [Options]`
64+
65+
| Option | Description | Usage
66+
| :---: | :---: | :---: |
67+
| -C, --sha, --commit-sha | Commit SHA (with 40 chars) | Required
68+
|--parent-sha | SHA (with 40 chars) of what should be the parent of this commit | Optional
69+
|-P, --pr, --pull-request-number| Specify the pull request number manually. Used to override pre-existing CI environment variables | Optional
70+
|-B, --branch | Branch to which this commit belongs to | Optional
71+
|-r, --slug | owner/repo slug used instead of the private repo token in Self-hosted | Required
72+
|-t, --token | Codecov upload token | Required
73+
|--git-service | Git Provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_server | Required
74+
|--help | Shows usage, and command options
75+
76+
77+
## create-report
78+
`codecovcli create-report [OPTIONS]`
79+
80+
| Option | Description | Usage
81+
| :---: | :---: | :---: |
82+
| -C, --sha, --commit-sha | Commit SHA (with 40 chars) | Required
83+
|-r, --slug | owner/repo slug used instead of the private repo token in Self-hosted | Required
84+
|-t, --token | Codecov upload token | Required
85+
|--git-service | Git Provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_server | Required
86+
|--code| The code of the report. This is used in local uploading to isolate local reports from regular or cloud reports uploaded to codecov so they don't get merged. It's basically a name you give to your report e.g. local-report. | Optional
87+
|--help | Shows usage, and command options
88+
89+
## do-upload
90+
`codecovcli do-upload [OPTIONS]`
91+
92+
| Option | Description | Usage
93+
| :---: | :---: | :---: |
94+
|-C, --sha, --commit-sha| Commit SHA (with 40 chars) | Required
95+
|--report-code | The code of the report defined when creating the report. If unsure, leave default | Optional
96+
|--network-root-folder | Root folder from which to consider paths on the network section default: (Current working directory) | Optional
97+
|-s, --dir, --coverage-files-search-root-folder | Folder where to search for coverage files default: (Current Working Directory) | Optional
98+
|--exclude, --coverage-files-search-exclude-folder | Folders to exclude from search | Optional
99+
|-f, --file, --coverage-files-search-direct-file | Explicit files to upload | Optional
100+
|-b, --build, --build-code | Specify the build number manually | Optional
101+
|--build-url | The URL of the build where this is running | Optional
102+
|--job-code | The job code for the CI run | Optional
103+
|-t, --token | Codecov upload token | Required
104+
|-n, --name | Custom defined name of the upload. Visible in Codecov UI | Optional
105+
|-B, --branch | Branch to which this commit belongs to | Optional
106+
|-r, --slug | owner/repo slug | Required
107+
|-P, --pr, --pull-request-number | Specify the pull request number manually. Used to override pre-existing CI environment variables | Optional
108+
|-e, --env, --env-var | Specify environment variables to be included with this build. | Optional
109+
|-F, --flag | Flag the upload to group coverage metrics. Multiple flags allowed. | Optional
110+
|--plugin | plugins to run. Options: xcode, gcov, pycoverage. The default behavior runs them all. | Optional
111+
|-Z, --fail-on-error | Exit with non-zero code in case of error uploading.|Optional
112+
|-d, --dry-run | Don't upload files to Codecov | Optional
113+
|--legacy, --use-legacy-uploader | Use the legacy upload endpoint | Optional
114+
|--git-service | Git Provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_server | Required
115+
|--help | Shows usage, and command options
116+
117+
## create-report-results
118+
`codecovcli create-report-results [OPTIONS]`
119+
120+
| Option | Description | Usage
121+
| :---: | :---: | :---: |
122+
|--commit-sha | Commit SHA (with 40 chars) | Required
123+
|--code | The code of the report. If unsure, leave default | Required
124+
|--slug | owner/repo slug | Required
125+
|--git-service | Git provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_server | Optional
126+
|-t, --token | Codecov upload token | Required
127+
|--help | Shows usage, and command options
128+
129+
## get-report-results
130+
`codecovcli get-report-results [OPTIONS]`
131+
132+
| Option | Description | Usage
133+
| :---: | :---: | :---: |
134+
|--commit-sha | Commit SHA (with 40 chars) | Required
135+
|--code | The code of the report. If unsure, leave default | Required
136+
|--slug | owner/repo slug | Required
137+
|--git-service | Git provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_server | Optional
138+
|-t, --token | Codecov upload token | Required
139+
|--help | Shows usage, and command options
140+
141+
## pr-base-picking
142+
`codecovcli pr-base-picking [OPTIONS]`
143+
144+
| Option | Description | Usage
145+
| :---: | :---: | :---: |
146+
|--base-sha | Base commit SHA (with 40 chars) | Required
147+
|--pr | Pull Request id to associate commit with | Required
148+
|--slug | owner/repo slug | Required
149+
|-t, --token| Codecov upload token | Required
150+
|--service | Git provider. Options: github, gitlab, bitbucket, github_enterprise, gitlab_enterprise, bitbucket_server | Optional
151+
|--help | Shows usage, and command options
152+
153+
# How to upload to Codecov
154+
In your CI workflow, you need to add these commands:
28155
```
29-
codecovcli --auto-load-params-from circleci do-upload
156+
pip install codecovcli
157+
codecovcli create-commit
158+
codecovcli create-report
159+
codecovcli do-upload
30160
```
161+
You can customize the commands with the options aligned with each command.
31162

32-
and pass parameters as you see fit. You can get help on
33-
163+
# How to Local upload:
164+
If you CI workflow takes too much time to run, and you have to wait for it to finish to know the coverage results, you can make your changes locally, make a PR and then run these commands:
34165
```
35-
codecovcli --help
166+
pip install codecovcli
167+
codecovcli create-commit
168+
codecovcli create-report --code <CODE>
169+
codecovcli do-upload --report-code <CODE>
170+
codecovcli create-report-results --code <CODE>
171+
codecovcli get-report-results --code <CODE>
36172
```
37173

38-
and
174+
Codecov will calculate the coverage results, and return them in your terminal, telling you whether your PR will fail or pass the coverage check.
39175

40-
```
41-
codecovcli do-upload --help
42-
```
43-
44-
# Running other commands
45-
46-
There are many nested commands here.
47176

48177
# Plugin System
49178

50179
In some of the commands, there is a plugin system. For most cases, one might find that changing them is not really needed. But in some cases, have some custom logic run would be beneficial
51180

181+
52182
WIP
53183

54-
# Development
184+
# Contributions
55185

56186
## Requirements
57187

@@ -62,8 +192,13 @@ Before installing, one should pull the submodules with
62192
```
63193
git submodule update --init
64194
```
195+
Then, install dependencies with
196+
```
197+
pip install -r requirements.txt
198+
python setup.py develop
199+
```
65200

66-
The c code shouldn't require anything on most places, but it might ask you to install compilers and stuff. Most of the times you can find the instructions online given the error messsage
201+
The c code shouldn't require anything in most places, but it might ask you to install compilers and stuff. Most of the times you can find the instructions online given the error message
67202

68203
## Guidelines
69204

@@ -75,11 +210,15 @@ There are a few guidelines when developing in this systems. We have a few notabl
75210

76211
# Releases
77212

78-
The standard way to making a new release is to get the up-to-date master branch locally and run the `tag.release` command from the Makefile.
213+
The standard way to making a new release is the following:
214+
1) Open a PR that increases the version number in setup.py. As a rule of thumb, just add one to the micro version (number most to the right).
79215

80-
`$ make tag.release version=v0.1.1`
216+
2) Get the up-to-date master branch locally and run the `tag.release` command from the Makefile.
217+
218+
`$ make tag.release version=v<VERSION_NUM>`
81219

82220
The version tag must match the regex defined on the Makefile (`tag_regex := ^v([0-9]{1,}\.){2}[0-9]{1,}([-_]\w+)?$`).
83-
Also keep in mind:
84-
* Releases with `test` word in them are created as `draft`
85-
* Releases with `beta` work in them are created as `pre-release`
221+
222+
>**Note**: \
223+
>Releases with `test` word in them are created as `draft`. \
224+
>Releases with `beta` work in them are created as `pre-release`.

0 commit comments

Comments
 (0)