diff --git a/README.md b/README.md index 6cc3a29..177018a 100644 --- a/README.md +++ b/README.md @@ -39,29 +39,29 @@ GitHub's JSON responses are parsed and returned to the caller as types of the fo Here's a table that matches up the provided `GitHubType`s with their corresponding API documentation, as well as alternative identifying values: -| type | alternative identifying property | link(s) to documentation | -|---------------|-------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `Owner` | login, e.g. `"octocat"` | [organizations](https://developer.github.com/v3/orgs/), [users](https://developer.github.com/v3/users/) | -| `Repo` | full_name, e.g. `"JuliaWeb/GitHub.jl"` | [repositories](https://developer.github.com/v3/repos/) | -| `Commit` | sha, e.g. `"d069993b320c57b2ba27336406f6ec3a9ae39375"` | [repository commits](https://developer.github.com/v3/repos/commits/) | -| `GitCommit` | sha, e.g. `"d069993b320c57b2ba27336406f6ec3a9ae39375"` | [raw git commits](https://developer.github.com/v3/git/commits/) | -| `Branch` | name, e.g. `master` | [repository branches](https://developer.github.com/v3/repos/#get-branch) | -| `Content` | path, e.g. `"src/owners/owners.jl"` | [repository contents](https://developer.github.com/v3/repos/contents/) | -| `Comment` | id, e.g. `162224613` | [commit comments](https://developer.github.com/v3/repos/comments/), [issue comments](https://developer.github.com/v3/issues/comments/), [PR review comments](https://developer.github.com/v3/pulls/comments/) | -| `Label` | name, e.g. `bug` | [issue labels](https://docs.github.com/en/rest/reference/issues#labels) -| `Status` | id, e.g. `366961773` | [commit statuses](https://developer.github.com/v3/repos/statuses/) | -| `PullRequest` | number, e.g. `44` | [pull requests](https://developer.github.com/v3/pulls/) | -| `PullRequestFile` | filename, e.g. `file1.txt` | [pull request files](https://docs.github.com/en/rest/reference/pulls#list-pull-requests-files) | -| `Issue` | number, e.g. `31` | [issues](https://developer.github.com/v3/issues/) | -| `Team` | id, e.g. `1` | [teams](https://developer.github.com/v3/orgs/teams) | -| `Gist` | id, e.g. `0bace7cc774df4b3a4b0ee9aaa271ef6` | [gists](https://developer.github.com/v3/gists) | -| `Review` | id, e.g. `1` | [reviews](https://developer.github.com/v3/pulls/reviews/) | -| `Blob` | sha, e.g. `"95c8d1aa2a7b1e6d672e15b67e0df4abbe57dcbe"` | [raw git blobs](https://developer.github.com/v3/git/blobs/) | -| `Tree` | sha, e.g. `"78e524d5e979e326a7c144ce195bf94ca9b04fa0"` | [raw git trees](https://developer.github.com/v3/git/trees/) | -| `Tag` | tag name, e.g. `v1.0` | [git tags](https://docs.github.com/en/rest/reference/git#tags) | -| `References` | reference name, e.g. `heads/master` (note: omits leading `refs/`) | [references](https://developer.github.com/v3/git/refs/) | -| `Secrets` | secret name, e.g. `TAGBOT_SECRET` | [secrets](https://developer.github.com/v3/actions/secrets/) | -| `DeployKeys` | id, e.g., 12345 | [deploy keys](https://docs.github.com/en/free-pro-team@latest/rest/reference/repos#deploy-keys) | +| type | alternative identifying property | link(s) to documentation | +|-------------------|-------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `Owner` | login, e.g. `"octocat"` | [organizations](https://developer.github.com/v3/orgs/), [users](https://developer.github.com/v3/users/) | +| `Repo` | full_name, e.g. `"JuliaWeb/GitHub.jl"` | [repositories](https://developer.github.com/v3/repos/) | +| `Commit` | sha, e.g. `"d069993b320c57b2ba27336406f6ec3a9ae39375"` | [repository commits](https://developer.github.com/v3/repos/commits/) | +| `GitCommit` | sha, e.g. `"d069993b320c57b2ba27336406f6ec3a9ae39375"` | [raw git commits](https://developer.github.com/v3/git/commits/) | +| `Branch` | name, e.g. `master` | [repository branches](https://developer.github.com/v3/repos/#get-branch) | +| `Content` | path, e.g. `"src/owners/owners.jl"` | [repository contents](https://developer.github.com/v3/repos/contents/) | +| `Comment` | id, e.g. `162224613` | [commit comments](https://developer.github.com/v3/repos/comments/), [issue comments](https://developer.github.com/v3/issues/comments/), [PR review comments](https://developer.github.com/v3/pulls/comments/) | +| `Label` | name, e.g. `bug` | [issue labels](https://docs.github.com/en/rest/reference/issues#labels) | +| `Status` | id, e.g. `366961773` | [commit statuses](https://developer.github.com/v3/repos/statuses/) | +| `PullRequest` | number, e.g. `44` | [pull requests](https://developer.github.com/v3/pulls/) | +| `PullRequestFile` | filename, e.g. `file1.txt` | [pull request files](https://docs.github.com/en/rest/reference/pulls#list-pull-requests-files) | +| `Issue` | number, e.g. `31` | [issues](https://developer.github.com/v3/issues/) | +| `Team` | id, e.g. `1` | [teams](https://developer.github.com/v3/orgs/teams) | +| `Gist` | id, e.g. `0bace7cc774df4b3a4b0ee9aaa271ef6` | [gists](https://developer.github.com/v3/gists) | +| `Review` | id, e.g. `1` | [reviews](https://developer.github.com/v3/pulls/reviews/) | +| `Blob` | sha, e.g. `"95c8d1aa2a7b1e6d672e15b67e0df4abbe57dcbe"` | [raw git blobs](https://developer.github.com/v3/git/blobs/) | +| `Tree` | sha, e.g. `"78e524d5e979e326a7c144ce195bf94ca9b04fa0"` | [raw git trees](https://developer.github.com/v3/git/trees/) | +| `Tag` | tag name, e.g. `v1.0` | [git tags](https://docs.github.com/en/rest/reference/git#tags) | +| `References` | reference name, e.g. `heads/master` (note: omits leading `refs/`) | [references](https://developer.github.com/v3/git/refs/) | +| `Secrets` | secret name, e.g. `TAGBOT_SECRET` | [secrets](https://developer.github.com/v3/actions/secrets/) | +| `DeployKeys` | id, e.g., 12345 | [deploy keys](https://docs.github.com/en/free-pro-team@latest/rest/reference/repos#deploy-keys) | You can inspect which fields are available for a type `G<:GitHubType` by calling `fieldnames(G)`. @@ -107,11 +107,12 @@ GitHub.jl implements a bunch of methods that make REST requests to GitHub's API. | `remove_collaborator(repo, user)` | `HTTP.Response` | [remove `user` as a collaborator from `repo`](https://developer.github.com/v3/repos/collaborators/#remove-collaborator) | | `collaborator_permission(repo, user)` | `HTTP.Response` | [get the `repo` permission of a collaborator](https://developer.github.com/v3/repos/collaborators/#get-repository-permissions-for-a-user) | | `stats(repo, stat[, attempts = 3])` | `HTTP.Response` | [get information on `stat` (e.g. "contributors", "code_frequency", "commit_activity", etc.)](https://developer.github.com/v3/repos/statistics/) | -| `topics(repo)` | `Vector{String}` | [get the list of topics of a repository.)](https://docs.github.com/en/rest/repos/repos#get-all-repository-topics) | -| `set_topics(repo, topics)` | `Vector{String}` | [set the list of topics of a repository.)](https://docs.github.com/en/rest/repos/repos#replace-all-repository-topics) | +| `topics(repo)` | `Vector{String}` | [get the list of topics of a repository.)](https://docs.github.com/en/rest/repos/repos#get-all-repository-topics) | +| `set_topics(repo, topics)` | `Vector{String}` | [set the list of topics of a repository.)](https://docs.github.com/en/rest/repos/repos#replace-all-repository-topics) | | `commit(repo, sha)` | `Commit` | [get the commit specified by `sha`](https://developer.github.com/v3/repos/commits/#get-a-single-commit) | | `commits(repo)` | `Tuple{Vector{Commit}, Dict}` | [get `repo`'s commits](https://developer.github.com/v3/repos/commits/#list-commits-on-a-repository) | -| `commits(repo, pr)` | `Tuple{Vector{Commit}, Dict}` | [get `pr`'s commits for `repo`](https://docs.github.com/en/rest/reference/pulls#list-commits-on-a-pull-request) | +| `commits(repo, pr)` | `Tuple{Vector{Commit}, Dict}` | [get `pr`'s commits for `repo`](https://docs.github.com/en/rest/reference/pulls#list-commits-on-a-pull-request) | +| `compare(repo, base, head)` | `Comparison` | [compare `repo`'s commits](https://docs.github.com/en/rest/commits/commits#compare-two-commits) | | `branch(repo, branch)` | `Branch` | [get the branch specified by `branch`](https://developer.github.com/v3/repos/#get-branch) | | `branches(repo)` | `Tuple{Vector{Branch}, Dict}` | [get `repo`'s branches](https://developer.github.com/v3/repos/#list-branches) | | `file(repo, path)` | `Content` | [get the file specified by `path`](https://developer.github.com/v3/repos/contents/#get-contents) | @@ -125,31 +126,31 @@ GitHub.jl implements a bunch of methods that make REST requests to GitHub's API. | `statuses(repo, ref)` | `Tuple{Vector{Status}, Dict}` | [get the statuses posted to `ref`](https://developer.github.com/v3/repos/statuses/#list-statuses-for-a-specific-ref) | | `status(repo, ref)` | `Status` | [get the combined status for `ref`](https://developer.github.com/v3/repos/statuses/#get-the-combined-status-for-a-specific-ref) | | `create_webhook(owner, repo)` | `Webhook` | [create a webhook for `repo`](https://developer.github.com/v3/repos/hooks/#create-a-hook) | -| `secrets(repo; auth)` | `Tuple{Vector{Secret}, Dict}` | [get names of all secrets for `repo`](https://developer.github.com/v3/actions/secrets/#list-repository-secrets) | -| `secret(repo, name; auth)` | `Secret` | [get status of secret in `repo`](https://developer.github.com/v3/actions/secrets/#get-a-repository-secret) | -| `create_secret(repo, name; value, auth)` | `nothing` | [create a secret for `repo`](https://developer.github.com/v3/actions/secrets/#create-or-update-a-repository-secret) | -| `delete_secret(repo, name; auth)` | `nothing` | [delete a secret for `repo`](https://developer.github.com/v3/actions/secrets/#delete-a-repository-secret) | -| `deploykeys(repo; auth)` | `Tuple{Vector{DeployKey}, Dict}`| [get all deploy keys for `repo`](https://docs.github.com/en/free-pro-team@latest/rest/reference/repos#list-deploy-keys) | -| `deploykey(repo, key; auth)` | `DeployKey` | [get the deploy `key` in `repo`](https://docs.github.com/en/free-pro-team@latest/rest/reference/repos#get-a-deploy-key) | -| `create_deploykey(repo; params=..., auth)` | `nothing` | [create a deploy key for `repo`](https://docs.github.com/en/free-pro-team@latest/rest/reference/repos#create-a-deploy-key) | -| `delete_deploykey(repo, key; auth)` | `nothing` | [delete a deploy key for `repo`](https://docs.github.com/en/free-pro-team@latest/rest/reference/repos#delete-a-deploy-key) | +| `secrets(repo; auth)` | `Tuple{Vector{Secret}, Dict}` | [get names of all secrets for `repo`](https://developer.github.com/v3/actions/secrets/#list-repository-secrets) | +| `secret(repo, name; auth)` | `Secret` | [get status of secret in `repo`](https://developer.github.com/v3/actions/secrets/#get-a-repository-secret) | +| `create_secret(repo, name; value, auth)` | `nothing` | [create a secret for `repo`](https://developer.github.com/v3/actions/secrets/#create-or-update-a-repository-secret) | +| `delete_secret(repo, name; auth)` | `nothing` | [delete a secret for `repo`](https://developer.github.com/v3/actions/secrets/#delete-a-repository-secret) | +| `deploykeys(repo; auth)` | `Tuple{Vector{DeployKey}, Dict}`| [get all deploy keys for `repo`](https://docs.github.com/en/free-pro-team@latest/rest/reference/repos#list-deploy-keys) | +| `deploykey(repo, key; auth)` | `DeployKey` | [get the deploy `key` in `repo`](https://docs.github.com/en/free-pro-team@latest/rest/reference/repos#get-a-deploy-key) | +| `create_deploykey(repo; params=..., auth)` | `nothing` | [create a deploy key for `repo`](https://docs.github.com/en/free-pro-team@latest/rest/reference/repos#create-a-deploy-key) | +| `delete_deploykey(repo, key; auth)` | `nothing` | [delete a deploy key for `repo`](https://docs.github.com/en/free-pro-team@latest/rest/reference/repos#delete-a-deploy-key) | #### Pull Requests and Issues -| method | return type | documentation | -|---------------------------------|------------------------------------|------------------------------------------------------------------------------------------------------------| -| `pull_request(repo, pr)` | `PullRequest` | [get the pull request specified by `pr`](https://developer.github.com/v3/pulls/#get-a-single-pull-request) | -| `pull_requests(repo)` | `Tuple{Vector{PullRequest}, Dict}` | [get `repo`'s pull requests](https://developer.github.com/v3/pulls/#list-pull-requests) | -| `pull_request_files(repo, pr)` | `Tuple{Vector{PullRequestFiles}, Dict}` | [get this `repo`'s `pr`'s file changes](https://docs.github.com/en/rest/reference/pulls#list-pull-requests-files) | -| `create_pull_request(repo)` | `PullRequest` | [create pull request in `repo`](https://developer.github.com/v3/pulls/#create-a-pull-request) | -| `update_pull_request(repo, pr)` | `PullRequest` | [update the given `pr` in `repo`](https://developer.github.com/v3/pulls/#update-a-pull-request) | -| `close_pull_request(repo, pr)` | `PullRequest` | [close the given `pr` in `repo`](https://developer.github.com/v3/pulls/#update-a-pull-request) | -| `issue(repo, issue)` | `Issue` | [get the issue specified by `issue`](https://developer.github.com/v3/issues/#get-a-single-issue) | -| `issues(repo)` | `Tuple{Vector{Issue}, Dict}` | [get `repo`'s issues](https://developer.github.com/v3/issues/#list-issues-for-a-repository) | -| `create_issue(repo)` | `Issue` | [create an issue in `repo`](https://developer.github.com/v3/issues/#create-an-issue) | -| `edit_issue(repo, issue)` | `Issue` | [edit `issue` in `repo`](https://developer.github.com/v3/issues/#edit-an-issue) | -| `reviews(repo, pr)` | `Tuple{Vector{PullRequest}, Dict}` | [get a `pr`'s reviews](https://developer.github.com/v3/pulls/reviews/#list-reviews-on-a-pull-request) | -| `dismiss_review(repo, review)` | `HTTP.Response` | [dismiss `review` in `repo`](https://developer.github.com/v3/pulls/reviews/#dismiss-a-pull-request-review) | +| method | return type | documentation | +|---------------------------------|-----------------------------------------|-------------------------------------------------------------------------------------------------------------------| +| `pull_request(repo, pr)` | `PullRequest` | [get the pull request specified by `pr`](https://developer.github.com/v3/pulls/#get-a-single-pull-request) | +| `pull_requests(repo)` | `Tuple{Vector{PullRequest}, Dict}` | [get `repo`'s pull requests](https://developer.github.com/v3/pulls/#list-pull-requests) | +| `pull_request_files(repo, pr)` | `Tuple{Vector{PullRequestFiles}, Dict}` | [get this `repo`'s `pr`'s file changes](https://docs.github.com/en/rest/reference/pulls#list-pull-requests-files) | +| `create_pull_request(repo)` | `PullRequest` | [create pull request in `repo`](https://developer.github.com/v3/pulls/#create-a-pull-request) | +| `update_pull_request(repo, pr)` | `PullRequest` | [update the given `pr` in `repo`](https://developer.github.com/v3/pulls/#update-a-pull-request) | +| `close_pull_request(repo, pr)` | `PullRequest` | [close the given `pr` in `repo`](https://developer.github.com/v3/pulls/#update-a-pull-request) | +| `issue(repo, issue)` | `Issue` | [get the issue specified by `issue`](https://developer.github.com/v3/issues/#get-a-single-issue) | +| `issues(repo)` | `Tuple{Vector{Issue}, Dict}` | [get `repo`'s issues](https://developer.github.com/v3/issues/#list-issues-for-a-repository) | +| `create_issue(repo)` | `Issue` | [create an issue in `repo`](https://developer.github.com/v3/issues/#create-an-issue) | +| `edit_issue(repo, issue)` | `Issue` | [edit `issue` in `repo`](https://developer.github.com/v3/issues/#edit-an-issue) | +| `reviews(repo, pr)` | `Tuple{Vector{PullRequest}, Dict}` | [get a `pr`'s reviews](https://developer.github.com/v3/pulls/reviews/#list-reviews-on-a-pull-request) | +| `dismiss_review(repo, review)` | `HTTP.Response` | [dismiss `review` in `repo`](https://developer.github.com/v3/pulls/reviews/#dismiss-a-pull-request-review) | #### Comments @@ -183,11 +184,11 @@ GitHub.jl implements a bunch of methods that make REST requests to GitHub's API. | method | return type | documentation | |------------------------------------------|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `labels(repo,issue)` | `Vector{Label}` | [list labels from `issue`](https://docs.github.com/en/rest/reference/issues#list-labels-for-an-issue) | -| `add_labels(repo, issue, labels)` | `Vector{Label}` | [add labels to an `issue`](https://docs.github.com/en/rest/reference/issues#add-labels-to-an-issue) | -| `set_labels(repo, issue, labels)` | `Vector{Label}` | [set the labels for an `issue`](https://docs.github.com/en/rest/reference/issues#set-labels-for-an-issue) -| `remove_all_labels(repo, issue)` | `HTTP.Response` | [remove all labels from an `issue`](https://docs.github.com/en/rest/reference/issues#remove-all-labels-from-an-issue) -| `remove_label(repo, issue, label)` | `HTTP.Response` | [remove a label from an `issue`](https://docs.github.com/en/rest/reference/issues#remove-a-label-from-an-issue) +| `labels(repo,issue)` | `Vector{Label}` | [list labels from `issue`](https://docs.github.com/en/rest/reference/issues#list-labels-for-an-issue) | +| `add_labels(repo, issue, labels)` | `Vector{Label}` | [add labels to an `issue`](https://docs.github.com/en/rest/reference/issues#add-labels-to-an-issue) | +| `set_labels(repo, issue, labels)` | `Vector{Label}` | [set the labels for an `issue`](https://docs.github.com/en/rest/reference/issues#set-labels-for-an-issue) | +| `remove_all_labels(repo, issue)` | `HTTP.Response` | [remove all labels from an `issue`](https://docs.github.com/en/rest/reference/issues#remove-all-labels-from-an-issue) | +| `remove_label(repo, issue, label)` | `HTTP.Response` | [remove a label from an `issue`](https://docs.github.com/en/rest/reference/issues#remove-a-label-from-an-issue) | #### Social Activity diff --git a/src/GitHub.jl b/src/GitHub.jl index 9cdf5d1..dd6e24c 100644 --- a/src/GitHub.jl +++ b/src/GitHub.jl @@ -110,6 +110,7 @@ include("repositories/statuses.jl") include("repositories/webhooks.jl") include("repositories/deploykeys.jl") include("repositories/secrets.jl") +include("repositories/compare.jl") # export ------- @@ -145,6 +146,10 @@ export # commits.jl commit, commits +export # compare.jl + Comparison, + compare + export # branches.jl Branch, branch, diff --git a/src/repositories/compare.jl b/src/repositories/compare.jl new file mode 100644 index 0000000..17fbe2a --- /dev/null +++ b/src/repositories/compare.jl @@ -0,0 +1,28 @@ +################### +# Comparison Type # +################### + +@ghdef mutable struct Comparison + url::Union{URIs.URI, Nothing} + html_url::Union{URIs.URI, Nothing} + permalink_url::Union{URIs.URI, Nothing} + diff_url::Union{URIs.URI, Nothing} + patch_url::Union{URIs.URI, Nothing} + base_commit::Union{Commit, Nothing} + merge_base_commit::Union{Commit, Nothing} + status::Union{String, Nothing} + ahead_by::Union{Int, Nothing} + behind_by::Union{Int, Nothing} + total_commits::Union{Int, Nothing} + commits::Union{Vector{Commit}, Nothing} + files::Union{Vector{Content}, Nothing} +end + +############### +# API Methods # +############### + +@api_default function compare(api::GitHubAPI, repo, base, head; options...) + result = gh_get_json(api, "/repos/$(name(repo))/compare/$(name(base))...$(name(head))"; options...) + return Comparison(result) +end diff --git a/test/read_only_api_tests.jl b/test/read_only_api_tests.jl index ebce193..033e08b 100644 --- a/test/read_only_api_tests.jl +++ b/test/read_only_api_tests.jl @@ -74,6 +74,13 @@ end @test name(branch(ghjl, "master"; auth = auth)) == "master" @test hasghobj("master", first(branches(ghjl; auth = auth))) + # test GitHub.compare + @test compare(ghjl, "master", "master~"; auth = auth).behind_by == 1 + let comparison = compare(ghjl, "master~", "master"; auth = auth) + @test comparison.ahead_by == 1 + @test length(comparison.commits) == 1 + end + # test GitHub.file, GitHub.directory, GitHub.readme, GitHub.permalink readme_file = file(ghjl, "README.md"; auth = auth) src_dir = first(directory(ghjl, "src"; auth = auth))