Skip to content

Commit 7b8ec9c

Browse files
zackproserzackproser
authored
Document use of --loglevel flag (#45)
1 parent 80685f3 commit 7b8ec9c

File tree

1 file changed

+39
-11
lines changed

1 file changed

+39
-11
lines changed

‎README.md‎

Lines changed: 39 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -229,6 +229,33 @@ git-xargs --github-org my-github-org \
229229
"$(pwd)/scripts/my-ruby-script.rb"
230230
```
231231
232+
## Debugging runtime errors
233+
234+
By default, `git-xargs` will conceal runtime errors as they occur because its log level setting is `INFO` if not overridden by the `--loglevel` flag.
235+
236+
To see all errors your script or command may be generating, be sure to pass `--loglevel DEBUG` when running your `git-xargs` command, like so:
237+
238+
```
239+
git-xargs --loglevel DEBUG \
240+
--repo zack-test-org/terraform-aws-eks \
241+
--branch-name master \
242+
--commit-message "add blank file" \
243+
--skip-pull-requests touch foo.txt
244+
```
245+
246+
When the log level is set to `debug` you should see new error output similar to the following:
247+
248+
```
249+
Total 195 (delta 159), reused 27 (delta 11), pack-reused 17 Repo=terraform-aws-eks
250+
[git-xargs] DEBU[2021-06-29T12:11:31-04:00] Created branch Branc
251+
h Name=refs/heads/master Repo=terraform-aws-eks
252+
[git-xargs] DEBU[2021-06-29T12:11:31-04:00] Error creating new branch Error
253+
="a branch named \"refs/heads/master\" already exists" Repo=terraform-aws-eks
254+
[git-xargs] DEBU[2021-06-29T12:11:31-04:00] Error encountered while processing repo Error
255+
="a branch named \"refs/heads/master\" already exists" Repo name=terraform-aws-eks
256+
257+
```
258+
232259
## Branch behavior
233260
234261
Passing the `--branch-name` (-b) flag is required when running `git-xargs`. If you specify the name of a branch that exists on your remote, its latest changes will be pulled locally prior to your command or script being run. If you specify the name of a new branch that does not yet exist on your remote, it will be created locally and pushed once your changes are committed.
@@ -335,17 +362,18 @@ echo "gruntwork-io/terragrunt gruntwork-io/terratest" | git-xargs \
335362
336363
`git-xargs` exposes several flags that allow you to customize its behavior to better suit your needs. For the latest info on flags, you should run `git-xargs --help`. However, a couple of the flags are worth explaining more in depth here:
337364
338-
| Flag | Description | Type | Required |
339-
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
340-
| `--branch-name` | You must specify the name of the branch to make your local and remote changes on. You can further control branching behavior via `--skip-pull-requests` as explained below | String | Yes |
341-
| `--repos` | If you want to specify many repos and manage them in files (which makes batching and testing easier) then use this flag to pass the filepath to a repos file. See [the repos file format](#option-2-flat-file-of-repository-names) for more information | String | No |
342-
| `--repo` | Use this flag to specify a single repo, e.g., `--repo gruntwork-io/cloud-nuke`. Can be passed multiple times to target several repos | String | No |
343-
| `--github-org` | If you want to target every repo in a Github org that your GITHUB_OAUTH_TOKEN has access to, pass the name of the Organization with this flag, to page through every repo via the Github API and target it | String | No |
344-
| `--commit-message` | The commit message to use when creating commits. If you supply this flag, but neither the optional `--pull-request-title` or `--pull-request-description` flags, then the commit message value will be used for all three. | String | No |
345-
| `--skip-pull-requests` | If you don't want any pull requests opened, but would rather have your changes committed directly to your specified branch, pass this flag. Note that it won't work if your Github repo is configured with branch protections on the branch you're trying to commit directly to! | Boolean | No |
346-
| `--skip-archived-repos` | If you want to exclude archived (read-only) repositories from the list of targeted repos, pass this flag. | Boolean | No |
347-
| `--dry-run` | If you are in the process of testing out `git-xargs` or your initial set of targeted repos, but you don't want to make any changes via the Github API (pushing your local changes or opening pull requests) you can pass the dry-run branch. This is useful because the output report will still tell you which repos would have been affected, without actually making changes via the Github API to your remote repositories. | Boolean | No |
348-
| `--max-concurrent-repos` | Limits the number of concurrent processed repositories. This is only useful if you encounter issues and need throttling when running on a very large number of repos. Default is `0` (Unlimited) | Integer | No |
365+
| Flag | Description | Type | Required |
366+
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | -------- |
367+
| `--branch-name` | You must specify the name of the branch to make your local and remote changes on. You can further control branching behavior via `--skip-pull-requests` as explained below | String | Yes |
368+
| `--loglevel` | Specify the log level of messages git-xargs should print to STDOUT at runtime. By default, this is INFO - so only INFO level messages will be visible. Pass DEBUG to see runtime errors encountered by your scripts or commands. Accepted levels are TRACE, DEBUG, INFO, WARNING, ERROR, FATAL and PANIC. Default: `INFO`. | String | Yes |
369+
| `--repos` | If you want to specify many repos and manage them in files (which makes batching and testing easier) then use this flag to pass the filepath to a repos file. See [the repos file format](#option-2-flat-file-of-repository-names) for more information | String | No |
370+
| `--repo` | Use this flag to specify a single repo, e.g., `--repo gruntwork-io/cloud-nuke`. Can be passed multiple times to target several repos | String | No |
371+
| `--github-org` | If you want to target every repo in a Github org that your GITHUB_OAUTH_TOKEN has access to, pass the name of the Organization with this flag, to page through every repo via the Github API and target it | String | No |
372+
| `--commit-message` | The commit message to use when creating commits. If you supply this flag, but neither the optional `--pull-request-title` or `--pull-request-description` flags, then the commit message value will be used for all three. | String | No |
373+
| `--skip-pull-requests` | If you don't want any pull requests opened, but would rather have your changes committed directly to your specified branch, pass this flag. Note that it won't work if your Github repo is configured with branch protections on the branch you're trying to commit directly to! | Boolean | No |
374+
| `--skip-archived-repos` | If you want to exclude archived (read-only) repositories from the list of targeted repos, pass this flag. | Boolean | No |
375+
| `--dry-run` | If you are in the process of testing out `git-xargs` or your intial set of targeted repos, but you don't want to make any changes via the Github API (pushing your local changes or opening pull requests) you can pass the dry-run branch. This is useful because the output report will still tell you which repos would have been affected, without actually making changes via the Github API to your remote repositories. | Boolean | No |
376+
| `--max-concurrent-repos` | Limits the number of concurrent processed repositories. This is only useful if you encounter issues and need throttling when running on a very large number of repos. Default is `0` (Unlimited) | Integer | No |
349377
350378
## Best practices, tips and tricks
351379

0 commit comments

Comments
 (0)