pax_global_header00006660000000000000000000000064150710042250014506gustar00rootroot0000000000000052 comment=6dc4ff700fc515157131b2106a17bb667579d449 ghub-5.0.1/000077500000000000000000000000001507100422500124365ustar00rootroot00000000000000ghub-5.0.1/.dir-locals.el000066400000000000000000000003571507100422500150740ustar00rootroot00000000000000((nil (indent-tabs-mode . nil)) (makefile-mode (indent-tabs-mode . t)) (git-commit-mode (git-commit-major-mode . git-commit-elisp-text-mode)) ("CHANGELOG" (nil (fill-column . 70) (mode . display-fill-column-indicator)))) ghub-5.0.1/.github/000077500000000000000000000000001507100422500137765ustar00rootroot00000000000000ghub-5.0.1/.github/ISSUE_TEMPLATE/000077500000000000000000000000001507100422500161615ustar00rootroot00000000000000ghub-5.0.1/.github/ISSUE_TEMPLATE/bug_report.md000066400000000000000000000010231507100422500206470ustar00rootroot00000000000000--- title: name: đŸĒŗ Bug report about: Report a defect. Do not use this for support requests and feature suggestions. --- Please explain (1) what behavior you expected (2) what behavior you observed (3) and how we can reproduce the issue. You don't have to quote the above lines to do that. Please include a backtrace in your report. In most cases doing: M-x toggle-debug-on-error RET and then going through the steps again should result in a backtrace. ---- now delete this line and everything above ---- ghub-5.0.1/.github/ISSUE_TEMPLATE/config.yml000066400000000000000000000013641507100422500201550ustar00rootroot00000000000000blank_issues_enabled: false contact_links: - name: "💡 Suggest a feature" url: https://github.com/magit/ghub/discussions about: Start a discussion suggest an improvement or a new feature. - name: "🆘 Ask the community for support" url: https://www.reddit.com/r/emacs about: Please also consider supporting others. - name: "🆘 Ask the maintainers for support" url: https://github.com/magit/ghub/discussions about: Please keep in mind that our bandwidth is limited. - name: "ℹī¸ Ghub FAQ" url: https://github.com/magit/ghub/wiki/FAQ about: Others might have had the same question before. - name: "ℹī¸ Ghub Manual" url: https://magit.vc/manual/ghub/#Top about: The fine manual may also be of use. ghub-5.0.1/.github/workflows/000077500000000000000000000000001507100422500160335ustar00rootroot00000000000000ghub-5.0.1/.github/workflows/compile.yml000066400000000000000000000002211507100422500202010ustar00rootroot00000000000000name: Compile on: [push, pull_request] jobs: compile: name: Compile uses: emacscollective/workflows/.github/workflows/compile.yml@main ghub-5.0.1/.github/workflows/manual.yml000066400000000000000000000004761507100422500200420ustar00rootroot00000000000000name: Manual on: push: branches: main tags: "v[0-9]+.[0-9]+.[0-9]+" jobs: manual: name: Manual uses: emacscollective/workflows/.github/workflows/manual.yml@main secrets: aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} ghub-5.0.1/.github/workflows/stats.yml000066400000000000000000000005071507100422500177160ustar00rootroot00000000000000name: Statistics on: push: branches: main schedule: - cron: '3 13 * * 1' jobs: stats: name: Statistics uses: emacscollective/workflows/.github/workflows/stats.yml@main secrets: aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} ghub-5.0.1/.gitignore000066400000000000000000000002221507100422500144220ustar00rootroot00000000000000/config.mk /docs/*.html /docs/*.info /docs/*.pdf /docs/*.texi /docs/.revdesc /docs/dir /docs/stats/ /lisp/*-autoloads.el /lisp/*.elc /docs/ghub/ ghub-5.0.1/.mailmap000066400000000000000000000000641507100422500140570ustar00rootroot00000000000000Zainab Ali zainab-ali ghub-5.0.1/CHANGELOG000066400000000000000000000306561507100422500136620ustar00rootroot00000000000000# -*- mode: org -*- * v5.0.1 2025-10-06 - Fixed two token cache invalidation failures. #180 * v5.0.0 2025-09-09 - Added new GraphQL query function ~ghub-query~, replacing ~ghub--graphql-vacuum~, ~ghub-graphql~ and ~ghub--graphql~ (which for the time being are still provided by the new ~ghub-legacy~ library), and ~ghub--graphql-synchronous~ (which was removed). 9790607, 3a3d209, 508e763 - Deprecated ~ghub-fetch-repository~, ~ghub-fetch-repository-discussion~, ~ghub-fetch-repository-issue~, ~ghub-fetch-repository-pullreq~ and ~ghub-fetch-repository-review-threads~. For the time being these functions are still defined in the new ~ghub-legacy~ library, but a future release will remove that. Such high-level and opinionated (i.e., optimized for the Forge package) functions are now considered to be beyond the scope of this package. d9d6559 - Removed the libraries ~buck~, ~glab~, ~gogs~ and ~gtea~, defining the functions ~{buck,glab,gogs,gtea}-{VERB,repository-id}~. For now these libraries are available as new, transitional packages ~buck~, ~glab~, ~gogs~ and ~gtea~. I recommend you stop using these wrapper functions and instead use ~(ghub-VERB ... :forge FORGE)~, where FORGE is one of ~bitbucket~, ~gitlab~, ~gogs~ and ~gitea~. - Added very rudimentary support for Forgejo. #177 - Fixed and improved host and username lookup. 6997e47 - Fixed bugs in getting the value of Git variables. d0576a1 * v4.3.2 2025-06-01 - It's now possible to wrap ~ghub--read-json-payload~ to depart from how it encodes json by default. #172 * v4.3.1 2025-04-28 - Fixed following paging links for Forgejo. #170 - Deprecated ~{buck,gogs,gtea}-{VERB}~ functions. * v4.3.0 2025-04-01 - Use the built-in native JSON support added in Emacs 30. In Emacs 29 the built-in support used the jansson library, but only if it was built with ~--with-json~. We already required Emacs 29 before, now we require "Emacs 29 with ~--with-json~, or Emacs 30". Support for the old ~json.el~ interface is dropped. Decoding should work as before. When it comes to encoding we inherit a backward incompatible change. Lists, or more accurately "JSON arrays", now have to be specified using Lisp vectors, not Lisp lists. #168 - ~ghub-fetch-repository~ now also fetches discussions and discussion categories. 26d5da1, a57baff - Display more debugging information; some of it only if ~ghub-debug~ is non-nil. * v4.2.2 2025-03-01 Thoughts and whitespace. * v4.2.1 2025-02-01 - Added new variable ~ghub-graphql-message-progress~. magit/forge#633 Bug fix: - When ~ghub--token~ does not find a token for ~host/path~, it now falls back to ~host~. See https://github.com/magit/forge/issues/720. * v4.2.0 2024-12-08 - At least Emacs 29.1 is required now. Bug fix: - Revert timeout changes from previous two releases. Url.el is such a pain. See https://github.com/magit/forge/issues/709. * v4.1.1 2024-10-01 Bug fix: - Fix the timeout handling from the previous release. * v4.1.0 2024-09-01 - Updated tooling. Bug fix: - Timeouts are now handled properly. 03d7161 * v4.0.0 2024-08-08 - When calling the callback for a REST request, the same buffer which was current when the request was made, is now temporarily made current. 2061136 - When calling the callback or errorback for a GraphQL request, the same buffer which was current when the request was made, is now temporarily made current. 2241135 - The default value of ~ghub-graphql-items-per-request~ had to be halved. We use deeply nested requests and Github's default (and suggested) limit of 100, often leads to timeouts on the server side. b3dd176 - It is now possible to specify how many items to fetch for a specific GraphQL edge using ~:edges INTEGER~. e6af790 - Added new ~paginate~ argument to ~ghub--graphql-vacuum~ and all its public callers (such as ~ghub-fetch-repository~). 337b884, b9c1600 - Taught ~ghub--graphql-vacuum~ to respects ~forge.graphqlItemLimit~. 11c31d1 - Added support for synchronous GraphQL queries, using the new ~ghub--graphql-synchronous~ function. a61da16 - Since there are now multiple ways to paginate results, make sure that the smallest value is used. ce7adcd - Setting the new ~ghub--graphql-debug~ variable causes debug information to be inserted into the ~*gsexp-encode*~ buffer. 87321cd - ~ghub-fetch-repository~ now also fetches the ~id~ of ~comments~, the ~stateReason~ of ~issues~, and ~isReadByViewer~ of ~issues~ and ~pullRequests~ 78a370f, 636a463, 13f3627, c59de91 Bug fixes: - 0d7c81e ghub-response-link-relations: Fix for GitLab - 2dc1cee ghub-graphql-error: Define missing error type - 3647748 ghub--retrieve: Better error if buffer is nil * v3.6.0 2023-05-13 - Queries can now be passed to ~ghub-graphql~ in the gsexp format. f3a2654 - ~ghub-fetch-repository~ fetches more information about Issues and PullRequests. fb9d33b 2c6671e - Gsexp now supports naming queries. 2c5ba23 - Added support for GitLab's GraphQL API. 0e61c0b - ~ghub--graphql-vacuum~ can now make synchronous requests. 142b0db - Added variable ~ghub-graphql-items-per-request~. 6a5de97 Bug fixes: - 8c4d0ba ghub--encode-payload: Drop invalid arguments to json-serialize - 0946102 ghub--url-encode-params: Handle lisp booleans - 5eed205 Add kludge for debbugs#54989 and rework kludge for debbugs#34341 - 7beed8c ghub--graphql-vacuum: Fall back to pretty-printing response Also contains various documentation updates, code clean-ups and build improvements. * v3.5.6 2022-03-25 - When encoding payloads, explicitly specify how to encode certain Lisp values in JSON. * v3.5.5 2022-02-16 - Define ~ghub--auth~ as a generic function. - Also included are several other improvements, updated documentation and bugfixes. - The experimental and unfinished support for the native json backend must not be used. It was merged prematurely. * v3.5.4 2021-10-02 - Add new ~sparse~ argument to ~ghub-fetch-repository~, making it possible to fetch only information about the repository itself, excluding data such as issues and pull-requests. * v3.5.3 2021-05-26 - If the username isn't set and the user decides to set it locally, then that resulted in an error. #124 * v3.5.2 2021-04-27 - Add new function ~ghub-fetch-review-threads~ and make ~ghub-fetch-respository~ fetch ~baseRefOid~ and ~headRefOid~. #110 - Add new ~headers~ argument to ~ghub-fetch-repository~, ~ghub-fetch-issue~ and ~ghub-fetch-pullreq~. #110 * v3.5.1 2020-12-27 - Add new ~headers~ keyword argument to ~ghub-graphql~. * v3.5.0 2020-11-21 - Add a kludge to work around a bug in Emacs that causes it to not respond correctly to http codes 401 and 409, causing the user to be asked for their username, which makes it very hard to debug the actual issue that caused to reject the provided information. [[https://github.com/magit/forge/issues/293][forge/293]] - Limit the kludge from v3.3.0 to Emacs releases that are affected. It was fixed in Emacs 27.1. * v3.4.2 2020-10-25 - Make sure base64 encoded credentials do not contain any newline characters. #118 * v3.4.1 2020-08-01 - Fix a regression introduced in v3.4.0. * v3.4.0 2020-07-20 - Remove the token setup wizard because (a) it only ever supported Github, (b) Github is about to remove support for that on their end, (c) it did not always work, and (d) when it couldn't be used, or failed, then it made things /more/ complicated. #113 - Various minor fixes and improvements. * v3.3.0 2020-01-19 - Add a kludge to work around a bug in Emacs versions before 26.3 that often but not always causes network connections to fail when using TLS1.3. On macOS use the workaround regardless of the Emacs version because the supposed bug fix does not appear to work there. Add a variable ~ghub-use-workaround-for-emacs-bug~ to allow users to opt in or out of using the kludge. #81 - Add a new library ~gsexp.el~ to encode S-expressions as GraphQl documents. Previously we used the third-party library ~graphql.el~ but using our own library gives us more flexibility. Currently it is rather incomplete and only intended for use by ~ghub-graphql~ but I might fill the gaps and add documentation eventually. I am not in a hurry though. #90 - No longer depend on ~dash~. - Handle some undocumented Bitbucket behavior. #97 - Add new option ~ghub-insecure-hosts~ to allow users to connect to insecure forges. #9 - Support Github instances that use an undocumented url-schema, which users report to have sighted in the wild. - ~ghub-fetch-repository~ now also fetches ~reviewRequests~. - Various bug fixes and improvements. * v3.2.0 2018-12-27 - Work around bug in Emacs versions before 26.1 that prevented newly created tokens from being used without the user invalidating ~auth-source~'s cache first. - Teach ~glab-repository-id~ about subgroups. * v3.1.0 2018-12-20 - Support GraphQL aliases. - Show number of GraphQL page currently being fetched in mode-line. - Add a default errorback for asynchronous REST requests, which shows the same information as would be shown for a failed synchronous request. - Signal an error if ~ghub-repository-id~ fails. - ~ghub-fetch-repository~ fetches a few more fields. * v3.0.0 2018-10-31 - Add support for Gitea, Gogs and Bitbucket. ~ghub.el~ supports these forges directly, but also add new libraries ~gtea.el~, ~gogs.el~ and ~buck.el~, which provide convenience wrappers just like the existing ~glab.el~. [[https://github.com/tarsius/ghub/issues/67][#67]] - No longer split the repository into multiple Melpa packages. I.e. the ~glab.el~ library is now part of the ~ghub~ package. - Add support for automatic GraphQL unpagination. [[https://github.com/tarsius/ghub/issues/68][#68]] GraphQL was designed around the idea that you should be able to "ask for what you need and get exactly that". Unfortunately this does not cover the "look, if I persist, then you are going to hand me over all the data anyway, so just cough it up already", which is what Forge needs. ~ghub--graphql-vacuum~ provides a way to unpaginate all cursors in the returned data without having to write a lot of boilerplate. Callers have to provide the query as an s-expression that corresponds to the root request. The queries needed to follow cursors in arbitrary locations within the returned data, are automatically derived from that query. ~ghub-fetch-repository~ fetches information about a repository. If also serves as an example for how to use ~ghub--graphql-vacuum~. The initial queries used by ~ghub-fetch-issue~ and ~ghub-fetch-pullreq~ are pre-narrowed variants of the initial query of ~ghub-fetch-repository~. Pre-narrowing is somewhat similar to the use of fragments, but unlike that, it doesn't result in lots of duplicated boilerplate and/or lots of variables. There is very little documentation and everything is still very much subject to change. - Bind ~url-show-message~ to ~nil~ so that the more useful messages displayed by the callers of this package are visible to the user instead of the less useful "Contacting host: api.github.com:443". - Sometimes Github returns an HTML document instead of the promised JSON when an error occurs. Try harder to extract some meaningful information from that document. - Work around a bug in older Emacsen that prevented ~auth-source~ from retrieving saved secrets. [[https://github.com/tarsius/ghub/issues/64][#64]] - Deal with a chicken and egg problem concerning 2fa. [[https://github.com/tarsius/ghub/issues/65][#65]] - Add new ~ghub-clear-caches~ command because if things go wonky it is nice to know it isn't the cache. - Add new ~ghub-repository-id~ function. This function works for all supported forges and always returns a string, even for less successful forges that can still get away with using integers as ids. - Add new ~ghub-graphql-rate-limit~ function. * v2.0.1 2018-04-19 (For this an earlier releases only the most important changes are mentioned.) - Various bug fixes. * v2.0.0 2018-03-20 - Support two-factor authentication. - Support asynchronous requests. - Support GraphQL. - Support Gitlab. * v1.3.0 2017-11-30 - Support basic authentication. - Fix various encoding issues. * v1.2.0 2017-04-26 - Support unauthenticated requests. - Support Github Enterprise instances. * v1.1.0 2016-08-07 - Bind ~json-false~ to ~nil~ instead of ~:json-false~. * v1.0.0 2016-04-20 - First release. ghub-5.0.1/LICENSE000066400000000000000000001045151507100422500134510ustar00rootroot00000000000000 GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007 Copyright (C) 2007 Free Software Foundation, Inc. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The GNU General Public License is a free, copyleft license for software and other kinds of works. The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things. To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others. For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights. Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it. For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions. Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users. Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free. The precise terms and conditions for copying, distribution and modification follow. TERMS AND CONDITIONS 0. Definitions. "This License" refers to version 3 of the GNU General Public License. "Copyright" also means copyright-like laws that apply to other kinds of works, such as semiconductor masks. "The Program" refers to any copyrightable work licensed under this License. Each licensee is addressed as "you". "Licensees" and "recipients" may be individuals or organizations. To "modify" a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a "modified version" of the earlier work or a work "based on" the earlier work. A "covered work" means either the unmodified Program or a work based on the Program. To "propagate" a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well. To "convey" a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying. An interactive user interface displays "Appropriate Legal Notices" to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion. 1. Source Code. The "source code" for a work means the preferred form of the work for making modifications to it. "Object code" means any non-source form of a work. A "Standard Interface" means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language. The "System Libraries" of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A "Major Component", in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it. The "Corresponding Source" for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work. The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source. The Corresponding Source for a work in source code form is that same work. 2. Basic Permissions. All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law. You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you. Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary. 3. Protecting Users' Legal Rights From Anti-Circumvention Law. No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures. When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures. 4. Conveying Verbatim Copies. You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program. You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee. 5. Conveying Modified Source Versions. You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions: a) The work must carry prominent notices stating that you modified it, and giving a relevant date. b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to "keep intact all notices". c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it. d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so. A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an "aggregate" if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate. 6. Conveying Non-Source Forms. You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways: a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange. b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge. c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b. d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements. e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d. A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work. A "User Product" is either (1) a "consumer product", which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, "normally used" refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product. "Installation Information" for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made. If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM). The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network. Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying. 7. Additional Terms. "Additional permissions" are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions. When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission. Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms: a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or d) Limiting the use for publicity purposes of names of licensors or authors of the material; or e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors. All other non-permissive additional terms are considered "further restrictions" within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying. If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms. Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way. 8. Termination. You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11). However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation. Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice. Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10. 9. Acceptance Not Required for Having Copies. You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so. 10. Automatic Licensing of Downstream Recipients. Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License. An "entity transaction" is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts. You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it. 11. Patents. A "contributor" is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's "contributor version". A contributor's "essential patent claims" are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, "control" includes the right to grant patent sublicenses in a manner consistent with the requirements of this License. Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version. In the following three paragraphs, a "patent license" is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To "grant" such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party. If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. "Knowingly relying" means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid. If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it. A patent license is "discriminatory" if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007. Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law. 12. No Surrender of Others' Freedom. If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program. 13. Use with the GNU Affero General Public License. Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such. 14. Revised Versions of this License. The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation. If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program. Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version. 15. Disclaimer of Warranty. THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 16. Limitation of Liability. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 17. Interpretation of Sections 15 and 16. If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee. END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . Also add information on how to contact you by electronic and paper mail. If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode: Copyright (C) This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, your program's commands might be different; for a GUI interface, you would use an "about box". You should also get your employer (if you work as a programmer) or school, if any, to sign a "copyright disclaimer" for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see . The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read . ghub-5.0.1/Makefile000066400000000000000000000025761507100422500141100ustar00rootroot00000000000000-include config.mk include default.mk .PHONY: lisp docs all: lisp docs help: $(info make all - generate lisp and manual) $(info make lisp - generate byte-code and autoloads) $(info make redo - re-generate byte-code and autoloads) $(info make docs - generate all manual formats) $(info make redo-docs - re-generate all manual formats) $(info make texi - generate texi manual) $(info make info - generate info manual) $(info make html - generate html manual file) $(info make html-dir - generate html manual directory) $(info make pdf - generate pdf manual) $(info make publish - publish snapshot manuals) $(info make release - publish release manuals) $(info make stats - generate statistics) $(info make stats-upload - publish statistics) $(info make clean - remove most generated files) @printf "\n" lisp: @$(MAKE) -C lisp lisp redo: @$(MAKE) -C lisp clean lisp docs: @$(MAKE) -C docs docs redo-docs: @$(MAKE) -C docs redo-docs texi: @$(MAKE) -C docs texi info: @$(MAKE) -C docs info html: @$(MAKE) -C docs html html-dir: @$(MAKE) -C docs html-dir pdf: @$(MAKE) -C docs pdf publish: @$(MAKE) -C docs publish release: @$(MAKE) -C docs release stats: @$(MAKE) -C docs stats stats-upload: @$(MAKE) -C docs stats-upload clean: @$(MAKE) -C lisp clean @$(MAKE) -C docs clean ghub-5.0.1/README.org000066400000000000000000000036551507100422500141150ustar00rootroot00000000000000** Ghub — Client libraries for the APIs of various Git forges Ghub provides basic support for using the APIs of various Git forges from Emacs packages. Originally it only supported the Github REST API, but now it also supports the Github GraphQL API as well as the REST APIs of Gitlab, Gitea, Gogs and Bitbucket. Ghub abstracts access to API resources using only a handful of basic functions such as ~ghub-get~. These are convenience wrappers around ~ghub-request~. Additional forge-specific wrappers like ~glab-put~, ~gtea-put~, ~gogs-post~ and ~buck-delete~ are also available. Ghub does not provide any resource-specific functions, with the exception of ~FORGE-repository-id~. When accessing Github, then Ghub handles the creation and storage of access tokens using a setup wizard to make it easier for users to get started. The tokens for other forges have to be created manually. Ghub is intentionally limited to only provide these two essential features — basic request functions and guided setup — to avoid being too opinionated, which would hinder wide adoption. It is assumed that wide adoption would make life easier for users and maintainers alike, because then all packages that talk to forge APIs could be configured the same way. Please consult the [[https://magit.vc/manual/ghub][manual]] for more information. #+html:

#+html: Compile #+html: Manual #+html: MELPA Stable #+html: MELPA ghub-5.0.1/default.mk000066400000000000000000000017151507100422500144170ustar00rootroot00000000000000TOP := $(dir $(lastword $(MAKEFILE_LIST))) PKG = ghub ELS = $(PKG).el ELS += gsexp.el ELS += $(PKG)-graphql.el ELS += $(PKG)-legacy.el ELCS = $(ELS:.el=.elc) DEPS = compat DEPS += llama DEPS += treepy DOMAIN ?= magit.vc CFRONT_DIST ?= E2LUHBKU1FBV02 VERSION ?= $(shell test -e $(TOP).git && git describe --tags --abbrev=0 | cut -c2-) REVDESC := $(shell test -e $(TOP).git && git describe --tags) EMACS ?= emacs EMACS_ARGS ?= --eval "(progn \ (put 'if-let 'byte-obsolete-info nil) \ (put 'when-let 'byte-obsolete-info nil))" LOAD_PATH ?= $(addprefix -L ../../,$(DEPS)) LOAD_PATH += -L . ifndef ORG_LOAD_PATH ORG_LOAD_PATH = -L ../../org/lisp endif INSTALL_INFO ?= $(shell command -v ginstall-info || printf install-info) MAKEINFO ?= makeinfo MANUAL_HTML_ARGS ?= --css-ref /assets/page.css GITSTATS ?= gitstats GITSTATS_DIR ?= $(TOP)docs/stats GITSTATS_ARGS ?= -c style=https://magit.vc/assets/stats.css -c max_authors=999 ghub-5.0.1/docs/000077500000000000000000000000001507100422500133665ustar00rootroot00000000000000ghub-5.0.1/docs/.orgconfig000066400000000000000000000030471507100422500153500ustar00rootroot00000000000000# -*- mode:org -*- # Copyright (C) 2021-2024 Jonas Bernoulli # SPDX-License-Identifier: GPL-3.0-or-later # URL: https://github.com/emacscollective/org-macros # Visit that to see these macros in a human-readable format. #+language: en #+options: H:4 num:3 toc:2 compact-itemx:t #+property: header-args :eval never #+macro: year (eval (format-time-string "%Y")) #+macro: version (eval (if-let ((tag (ignore-errors (car (process-lines "git" "describe" "--exact-match"))))) (concat "version " (substring tag 1)) (or (ignore-errors (car (process-lines "git" "describe"))) (concat "version " (or $1 ""))))) #+macro: kbd (eval (format "@@texinfo:@kbd{@@%s@@texinfo:}@@" (let (case-fold-search) (replace-regexp-in-string (regexp-opt '("BS" "TAB" "RET" "ESC" "SPC" "DEL" "LFD" "DELETE" "SHIFT" "Ctrl" "Meta" "Alt" "Cmd" "Super" "UP" "LEFT" "RIGHT" "DOWN") 'words) "@@texinfo:@key{@@\\&@@texinfo:}@@" $1 t)))) #+macro: kbdvar (eval (format "@@texinfo:@kbd{@@%s@@texinfo:}@@" (let (case-fold-search) (replace-regexp-in-string "<\\([a-zA-Z-]+\\)>" "@@texinfo:@var{@@\\1@@texinfo:}@@" (replace-regexp-in-string (regexp-opt '("BS" "TAB" "RET" "ESC" "SPC" "DEL" "LFD" "DELETE" "SHIFT" "Ctrl" "Meta" "Alt" "Cmd" "Super" "UP" "LEFT" "RIGHT" "DOWN") 'words) "@@texinfo:@key{@@\\&@@texinfo:}@@" $1 t) t)))) #+macro: codevar (eval (format "@@texinfo:@code{@@%s@@texinfo:}@@" (let (case-fold-search) (replace-regexp-in-string "\\([A-Z][A-Z-]+\\)" "@@texinfo:@var{@@\\&@@texinfo:}@@" $1 t)))) #+macro: var @@texinfo:@var{@@$1@@texinfo:}@@ #+macro: dfn @@texinfo:@dfn{@@$1@@texinfo:}@@ ghub-5.0.1/docs/Makefile000066400000000000000000000100531507100422500150250ustar00rootroot00000000000000-include ../config.mk include ../default.mk docs: texi info html html-dir pdf texi: $(PKG).texi info: $(PKG).info dir html: $(PKG).html html-dir: $(PKG)/index.html pdf: $(PKG).pdf ORG_ARGS = --batch -Q $(ORG_LOAD_PATH) ORG_EVAL += --eval "(setq indent-tabs-mode nil)" ORG_EVAL += --eval "(setq org-src-preserve-indentation nil)" ORG_EVAL += --eval "\ (defun org-texinfo--sanitize-content (text)\ (replace-regexp-in-string \"[@@{}]\" \"@@\\&\" text))" ORG_EVAL += --funcall org-texinfo-export-to-texinfo redo-docs: @touch $(PKG).org @make docs .revdesc: ; _ := $(shell test "$(REVDESC)" = "$$(cat .revdesc 2> /dev/null)" ||\ echo "$(REVDESC)" > .revdesc) %.texi: %.org .orgconfig .revdesc @printf "Generating $@\n" @$(EMACS) $(ORG_ARGS) $< $(ORG_EVAL) %.info: %.texi @printf "Generating $@\n" @$(MAKEINFO) --no-split $< -o $@ dir: $(PKG).info @printf "Generating $@\n" @printf "%s" $^ | xargs -n 1 $(INSTALL_INFO) --dir=$@ HTML_FIXUP_CSS = '//a\ \ \n\ \n\ \n\ \n\ \n' HTML_FIXUP_ONLOAD = 's///' HTML_FIXUP_MENU = '/<\/body>/i
<\/div>' HTML_FIXUP_HREF = 's% href="\.\./\(.*\)_html/% href="../\1/%' %.html: %.texi @printf "Generating $@\n" @$(MAKEINFO) --html --no-split $(MANUAL_HTML_ARGS) $< @sed -i -e $(HTML_FIXUP_CSS) -e $(HTML_FIXUP_ONLOAD) -e $(HTML_FIXUP_MENU) $@ %/index.html: %.texi @printf "Generating $(PKG)/*.html\n" @rm -rf $(PKG) @$(MAKEINFO) --html -o $(PKG)/ $(MANUAL_HTML_ARGS) $< @for f in $$(find $(PKG) -name '*.html') ; do \ sed -i -e $(HTML_FIXUP_CSS) -e $(HTML_FIXUP_ONLOAD) -e $(HTML_FIXUP_MENU) -e $(HTML_FIXUP_HREF) $$f ; \ done %.pdf: %.texi @printf "Generating $@\n" @texi2pdf --clean $< > /dev/null PUBLISH_PATH ?= /manual/ RELEASE_PATH ?= /manual/$(VERSION)/ S3_BUCKET ?= s3://$(DOMAIN) PUBLISH_TARGET = $(S3_BUCKET)$(PUBLISH_PATH) RELEASE_TARGET = $(S3_BUCKET)$(RELEASE_PATH) CFRONT_PATHS = $(PKG).html $(PKG).pdf $(PKG)/* comma := , empty := space := $(empty) $(empty) publish: redo-docs @aws s3 cp $(PKG).html $(PUBLISH_TARGET) @aws s3 cp $(PKG).pdf $(PUBLISH_TARGET) @aws s3 sync $(PKG) $(PUBLISH_TARGET)$(PKG)/ @printf "Generating CDN invalidation\n" @aws cloudfront create-invalidation --distribution-id $(CFRONT_DIST) --paths \ "$(subst $(space),$(comma),$(addprefix $(PUBLISH_PATH),$(CFRONT_PATHS)))" > /dev/null release: redo-docs @aws s3 cp $(PKG).html $(RELEASE_TARGET) @aws s3 cp $(PKG).pdf $(RELEASE_TARGET) @aws s3 sync $(PKG) $(RELEASE_TARGET)$(PKG)/ @aws s3 cp $(PUBLISH_TARGET)dir.html $(RELEASE_TARGET)dir.html @aws s3 cp $(PUBLISH_TARGET)dir/index.html $(RELEASE_TARGET)dir/index.html @printf "Generating CDN invalidation\n" @aws cloudfront create-invalidation --distribution-id $(CFRONT_DIST) --paths \ "$(subst $(space),$(comma),$(addprefix $(RELEASE_PATH),$(CFRONT_PATHS)))" > /dev/null .PHONY: stats stats: @printf "Generating statistics\n" @$(GITSTATS) $(GITSTATS_ARGS) $(TOP) $(GITSTATS_DIR) stats-upload: @printf "Uploading statistics...\n" @aws s3 sync $(GITSTATS_DIR) $(S3_BUCKET)/stats/$(PKG) @printf "Uploaded to $(S3_BUCKET)/stats/$(PKG)\n" @printf "Generating CDN invalidation\n" @aws cloudfront create-invalidation \ --distribution-id $(CFRONT_DIST) --paths "/stats/*" > /dev/null CLEAN = $(PKG).info dir $(PKG) $(PKG).html $(PKG).pdf clean: @printf " Cleaning docs/*...\n" @rm -rf $(CLEAN) ghub-5.0.1/docs/ghub.org000066400000000000000000001020351507100422500150250ustar00rootroot00000000000000#+title: Ghub User and Developer Manual :PREAMBLE: #+author: Jonas Bernoulli #+email: emacs.ghub@jonas.bernoulli.dev #+date: 2017-{{{year}}} #+texinfo_dir_category: Emacs #+texinfo_dir_title: Ghub: (ghub). #+texinfo_dir_desc: Client library for the Github API. #+subtitle: for version 5.0.1 #+setupfile: .orgconfig Ghub is an Emacs library that is used by various packages to access the APIs of various instances of various Git forge implementations. #+texinfo: @noindent This manual is for Ghub version 5.0.1. #+texinfo: @insertcopying :END: * Introduction Ghub is an Emacs library that is used by various packages to access the APIs of various instances of various Git forge implementations. A forge is a web-based collaborative software platform for developing and distributing computer applications. Examples include Github and Gitlab. * Getting Started This manual guides you through the steps that are necessary to use the Forge package and/or to make a request using just Ghub itself, such as this: #+begin_src emacs-lisp (ghub-request "GET" "/user") #+end_src To be able to do that, Ghub needs to know who you want to talk to, who you are, and how you are going to prove the latter to the former. Additionally Ghub wants to know on behalf of which Emacs package it is making a request. So the question of "who is making the request" has to be rephrased as "which human (or bot) is using what (Emacs) package to make the request". If, for example, the human known as "tarsius" is using the ~forge~ package, then that is represented in some places using the string "tarsius^forge". ** Basic Concepts, Arguments and Variables (If you are trying to configure Forge for https://github.com and/or https://gitlab.com, then you can skip this section.) Originally Ghub supported only Github but now it also supports Gitlab, Gitea, Gogs and Bitbucket. Because of that, the function ~ghub-request~ defaults to acting on a ~github~ forge, but can be told to act on other forges using the FORGE argument. The FORGE argument only specifies what kind of forge we are accessing, not which host specifically. The HOST argument can be used to select the instance. For some forges a default instance is defined: - Forge ~github~ defaults to host ~api.github.com~. - Forge ~gitlab~ defaults to host ~gitlab.com/api/v4~. - Forge ~bitbucket~ defaults to host ~api.bitbucket.org/2.0~. - No canonical host exists for the ~gitea~ and ~gogs~ forges and ~localhost:3000/api/v1~ is used as the default host in both cases. Together the FORGE and HOST arguments specify the forge type and instance. In addition to that, it is also necessary to specify on whose behalf the request is being made, which can be done using the USERNAME and AUTH arguments. For example: #+begin_src emacs-lisp (ghub-request "GET" "/user" nil :forge 'github :host "api.github.com" :username "tarsius" :auth 'forge) #+end_src Having to specify these arguments for every request is inconvenient. Additional variables and convenience functions can be used to make that unnecessary in most cases. (But for debugging purposes the above explicit form is very useful. You will obviously have to change the value of USERNAME and you should use ~ghub~ as AUTH when first trying this at home.) These variables can be set globally and/or for a specific repository. - For "api.github.com" (aka the API of https://github.com) the Git variable ~github.user~ specifies the user. - For another ~github~ instance the Git variable ~github.HOST.user~ specifies the user. The HOST in that variable name is the same as the value of the HOST argument of the called function. - Instead of specifying the HOST in every function call, the Git variable ~github.host~ can be used. This should only be set locally. These ~github~ specific variables are discussed in more detail in [[*Github Configuration Variables]]. #+texinfo: @noindent For ~gitlab~ and ~bitbucket~ forges similar variables are available: - ~gitlab.user~ specifies the https://gitlab.com user. - ~gitlab.HOST.user~ specifies the user for the HOST ~gitlab~ instance. - ~gitlab.host~ specifies the ~gitlab~ host, unless the HOST argument is non-nil - ~bitbucket.user~ specifies the https://bitbucket.org user. - ~bitbucket.HOST.user~ specifies the user for the HOST ~bitbucket~ instance. - ~bitbucket.host~ specifies the ~bitbucket~ host, unless the HOST argument is non-nil. For the ~gitea~ and ~gogs~ forges some similar variables are available, however for some of the ~ghub.*~ variables no equivalent variable exist for these two forges: - ~gitea.user~ is *not* used because no canonical ~gitea~ instance exists. - ~gitea.HOST.user~ specifies the user for the HOST ~gitea~ instance. - ~gitea.host~ specifies the ~gitea~ host, unless the HOST argument is non-nil - ~gogs.user~ is *not* used because no canonical ~gogs~ instance exists. - ~gogs.HOST.user~ specifies the user for the HOST ~gogs~ instance. - ~gogs.host~ specifies the ~gogs~ host, unless the HOST argument is non-nil ** Setting the Username Ghub needs to know your username, which you use on the host that you want it to connect to. For each host a different Git variable has to be set, to specify the username on that host. More than one variable is needed, because you might use different usernames on different hosts. *** Setting your Github.com Username :PROPERTIES: :UNNUMBERED: notoc :END: To inform Ghub about your "github.com" username do this: #+begin_src shell git config --global github.user USERNAME #+end_src If you need to identify as another user in a particular repository, then you have to set that variable locally: #+begin_src shell cd /path/to/repo git config --local github.user USERNAME #+end_src *** Setting your Gitlab.com Username :PROPERTIES: :UNNUMBERED: notoc :END: To inform Ghub about your "gitlab.com" username do this: #+begin_src shell git config --global gitlab.user USERNAME #+end_src If you need to identify as another user in a particular repository, then you have to set that variable locally: #+begin_src shell cd /path/to/repo git config --local gitlab.user USERNAME #+end_src Make sure you use the correct USERNAME for this forge/host. It might not be the same as on "github.com"! *** Setting your Github Enterprise Username :PROPERTIES: :UNNUMBERED: notoc :END: For Github Enterprise instances you have to specify where the API can be accessed and a different variable has to be used to set the username. For example if the API is available at ~https://example.com/api/v3~, then you should do this: #+begin_src shell git config --global github.example.com/api/v3.user USERNAME #+end_src Make sure you use the correct USERNAME for this instance. It might not be the same as on "github.com"! Doing this only tells Ghub who you are on this host, additionally you have to tell Ghub which repositories are connected to that forge/host, like so: #+begin_src shell cd /path/to/repo git config --local github.host example.com/api/v3 #+end_src *** Setting your Username for Other Hosts and/or Forges :PROPERTIES: :UNNUMBERED: notoc :END: To inform Ghub about your username on HOST (a FORGE instance) do this: #+begin_src shell git config --global FORGE.HOST.user USERNAME #+end_src FORGE can be one of ~bitbucket~, ~gitea~ or ~gogs~. It can also be ~github~ or ~gitlab~; but if that is the case, then you should look at the preceding sections instead, which discuss these cases specifically. HOST identifies the instance. This actually points at the top-level endpoint of the API and may contain path components, e.g.: ~example.com/api~. If you need to identify as another user in a particular repository, then you have to set that variable locally: #+begin_src shell cd /path/to/repo git config --local FORGE.HOST.user USERNAME #+end_src ** Creating and Storing a Token *** Creating a Token To create a token, use the web interface of the host you want to connect to. Here is a list of pages to do this for certain popular hosts: - https://github.com/settings/tokens - https://gitlab.com/-/user_settings/personal_access_tokens For other forges we cannot provide a functioning URL because they contain unknown values such as your name. Just go to the general settings page of the respective host and then go from there. Except on ~gitea~ and ~gogs~ each token can be limited to certain "scopes", i.e., it is possible to limit for which purposes any given token can be used. Before you create a token to be used for a certain package, you should consult the documentation of that package, which in turn should tell you which scopes are needed and why. The Forge package for example does so in [[info:forge#Token Creation]]. *** Storing a Token Please also see [[info:auth]] for all the gory details about Auth-Source. The variable ~auth-sources~ controls how and where Auth-Source keeps its secrets. The default value is a list of three files: ~("~/.authinfo" "~/.authinfo.gpg" "~/.netrc")~, but to avoid confusion you should make sure that only one of these files exists, and then you should also adjust the value of the variable to only ever use that file, for example: #+begin_src emacs-lisp (setq auth-sources '("~/.authinfo")) #+end_src In ~~/.authinfo~ secrets are stored in plain text. If you don't want that, then you should use the encrypted ~~/.authinfo.gpg~ instead: #+begin_src emacs-lisp (setq auth-sources '("~/.authinfo.gpg")) #+end_src Auth-Source also supports storing secrets in various external key-chains. See info:auth for more information. The default Auth-Source backends only support storing three values per entry; the "machine", the "login" and the "password". Because Ghub uses separate tokens for each package, it has to squeeze four values into those three slots, and it does that by using "USERNAME^PACKAGE" as the "login". Assuming your *Github* username is "ziggy", the package is named "forge", and you want to access *Github.com* with the *token* "012345abcdef...", an entry in one of the three mentioned files would then look like this: #+begin_src example machine api.github.com login ziggy^forge password 012345abcdef... #+end_src Assuming your *Gitlab* username is "ziggy", the package is named "forge", and you want to access *Gitlab.com* with the *token* "012345abcdef...", an entry in one of the three mentioned files would then look like this: #+begin_src example machine gitlab.com/api/v4 login ziggy^forge password 012345abcdef... #+end_src ** Github Configuration Variables The username and, unless you only use Github.com itself, the Github Enterprise instance have to be configured using Git variables. In rare cases it might also be necessary to specify the identity of the local machine, which is done using a lisp variable. - Variable: github.user :: The Github.com username. This should be set globally and if you have multiple Github.com user accounts, then you should set this locally only for those repositories that you want to access using the secondary identity. - Variable: github.HOST.user :: This variable serves the same purpose as ~github.user~ but for the Github Enterprise instance identified by ~HOST~. The reason why separate variables are used is that this makes it possible to set both values globally instead of having to set one of the values locally in each and every repository that is connected to the Github Enterprise instance, not Github.com. - Variable: github.host :: This variable should only be set locally for a repository and specifies the Github Enterprise edition that that repository is connected to. You should not set this globally because then each and every repository becomes connected to the specified Github Enterprise instance, including those that should actually be connected to Github.com. When this is undefined, then "api.github.com" is used (defined in the constant ~ghub-default-host~, which you should never attempt to change.) * API ** Their APIs Of course this manual does not cover the APIs of all forges that it supports, but for your convenience, here are the links to their API manuals: - Github: - https://docs.github.com/en/graphql (GraphQl) - https://docs.github.com/en/rest (REST) - Gitlab: - https://docs.gitlab.com/api - Gitea: - https://docs.gitea.com/next/development/api-usage - https://demo.gitea.com - Gogs: - https://gogs.io/docs - Bitbucket: - https://developer.atlassian.com/cloud/bitbucket ** Making REST Requests - Function: ghub-request method resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback url value error extra method* :: This function makes a request for ~RESOURCE~ using ~METHOD~. ~PARAMS~, ~QUERY~, ~PAYLOAD~ and/or ~HEADERS~ are alists holding additional request data. The response body is returned and the response headers are stored in the variable ~ghub-response-headers~. - ~METHOD~ is the HTTP method, given as a string. - ~RESOURCE~ is the resource to access, given as a string beginning with a slash. - ~PARAMS~, ~QUERY~, ~PAYLOAD~ and ~HEADERS~ are alists and are used to specify request data. All these arguments are alists that resemble the JSON expected and returned by the Github API. The keys are symbols and the values stored in the ~cdr~ (not the ~cadr~) can be strings, integers, or lists of strings and integers. The Github API documentation is vague on how data has to be transmitted and for a particular resource usually just talks about "parameters". Generally speaking when the ~METHOD~ is "HEAD" or "GET", then they have to be transmitted as a query, otherwise as a payload. - Use ~PARAMS~ to automatically transmit like ~QUERY~ or ~PAYLOAD~ would depending on ~METHOD~. - Use ~QUERY~ to explicitly transmit data as a query. - Use ~PAYLOAD~ to explicitly transmit data as a payload. Instead of an alist, ~PAYLOAD~ may also be a string, in which case it gets encoded as UTF-8 but is otherwise transmitted as-is. - Use ~HEADERS~ for those rare resources that require that the data is transmitted as headers instead of as a query or payload. When that is the case, then the Github API documentation usually mentions it explicitly. - If ~SILENT~ is non-nil, then progress reports and the like are not messaged. - If ~UNPAGINATE~ is t, then this function makes as many requests as necessary to get all values. If ~UNPAGINATE~ is a natural number, then it gets at most that many pages. For any other non-nil value it raises an error. - If ~NOERROR~ is non-nil, then no error is raised if the request fails and ~nil~ is returned instead. If ~NOERROR~ is ~return~, then the error payload is returned instead of ~nil~. - If ~READER~ is non-nil, then it is used to read and return from the response buffer. The default is ~ghub--read-json-payload~. For the very few resources that do not return JSON, you might want to use ~ghub--decode-payload~. - If ~USERNAME~ is non-nil, then the request is made on behalf of that user. It is better to specify the user using the Git variable ~github.user~ for "api.github.com", or ~github.HOST.user~ if connecting to a Github Enterprise instance. - Each package that uses Ghub should use its own token. If ~AUTH~ is ~nil~ or unspecified, then the generic ~ghub~ token is used instead. This is only acceptable for personal utilities. A package that is distributed to other users should always use this argument to identify itself, using a symbol matching its name. Package authors who find this inconvenient should write a wrapper around this function and possibly for the method-specific functions as well. Beside ~nil~, some other symbols have a special meaning too. ~none~ means to make an unauthorized request. ~basic~ means to make a password based request. If the value is a string, then it is assumed to be a valid token. ~basic~ and an explicit token string are only intended for internal and debugging uses. If ~AUTH~ is a package symbol, then the scopes are specified using the variable ~AUTH-github-token-scopes~. It is an error if that is not specified. See ~ghub-github-token-scopes~ for an example. - If ~HOST~ is non-nil, then connect to that Github instance. This defaults to "api.github.com". When a repository is connected to a Github Enterprise instance, then it is better to specify that using the Git variable ~github.host~ instead of using this argument. - If ~FORGE~ is ~gitlab~, then connect to Gitlab.com or, depending on ~HOST~, to another Gitlab instance. - If ~CALLBACK~ and/or ~ERRORBACK~ is non-nil, then this function makes one or more asynchronous requests and calls ~CALLBACK~ or ~ERRORBACK~ when finished. If no error occurred, then it calls ~CALLBACK~, unless that is ~nil~. If an error occurred, then it calls ~ERRORBACK~, or if that is nil, then ~CALLBACK~. ~ERRORBACK~ can also be ~t~, in which case it signals instead. ~NOERROR~ is ignored for all asynchronous requests. Both callbacks are called with four arguments. 1. For ~CALLBACK~, the combined value of the retrieved pages. For ~ERRORBACK~, the error that occurred when retrieving the last page. 2. The headers of the last page as an alist. 3. Status information provided by ~url-retrieve~. Its ~:error~ property holds the same information as the first argument to ~ERRORBACK~. 4. A ~ghub--req~ struct, which can be passed to ~ghub-continue~ (which see) to retrieve the next page, if any. - Function: ghub-continue args :: If there is a next page, then this function retrieves that. This function is only intended to be called from callbacks. If there is a next page, then that is retrieved and the buffer that the result will be loaded into is returned, or t if the process has already completed. If there is no next page, then return nil. Callbacks are called with four arguments (see ~ghub-request~). The forth argument is a ~ghub--req~ struct, intended to be passed to this function. A callback may use the struct's ~extra~ slot to pass additional information to the callback that will be called after the next request. Use the function ~ghub-req-extra~ to get and set the value of that slot. As an example, using ~ghub-continue~ in a callback like so: #+BEGIN_SRC emacs-lisp (ghub-get "/users/tarsius/repos" nil :callback (lambda (value _headers _status req) (unless (ghub-continue req) (setq my-value value)))) #+END_SRC is equivalent to: #+BEGIN_SRC emacs-lisp (ghub-get "/users/tarsius/repos" nil :unpaginate t :callback (lambda (value _headers _status _req) (setq my-value value))) #+END_SRC To demonstrate how to pass information from one callback to the next, here we record when we start fetching each page: #+BEGIN_SRC emacs-lisp (ghub-get "/users/tarsius/repos" nil :extra (list (current-time)) :callback (lambda (value _headers _status req) (push (current-time) (ghub-req-extra req)) (unless (ghub-continue req) (setq my-times (ghub-req-extra req)) (setq my-value value)))) #+END_SRC - Variable: ghub-response-headers :: A select few Github API resources respond by transmitting data in the response header instead of in the response body. Because there are so few of these inconsistencies, ~ghub-request~ always returns the response body. To access the response headers use this variable after ~ghub-request~ has returned. - Function: ghub-response-link-relations req headers payload :: This function returns an alist of the link relations in ~HEADERS~, or if optional ~HEADERS~ is nil, then those in ~ghub-response-headers~. When accessing a Bitbucket instance then the link relations are in ~PAYLOAD~ instead of ~HEADERS~, making their API merely RESTish and forcing this function to append those relations to the value of ~ghub-response-headers~, for later use when this function is called with ~nil~ for ~PAYLOAD~. ** Making GraphQL Requests - Function: ghub-graphql graphql &optional variables &key username auth host callback silent callback errorback value extra :: This function makes a GraphQL request using ~GRAPHQL~ and ~VARIABLES~ as inputs. ~GRAPHQL~ is a GraphQL string. ~VARIABLES~ is a JSON-like alist. The other arguments behave as for ~ghub-request~ (which see). The response is returned as a JSON-like alist. Even if the response contains ~errors~, this function does not raise an error. Cursor-handling is likewise left to the caller. ~ghub-graphql~ is a thin convenience wrapper around ~ghub-request~, similar to ~ghub-post~ and friends. While the latter only hard-code the value of the ~METHOD~ argument, the former also hard-codes ~RESOURCE~ and constructs ~PAYLOAD~ from ~GRAPHQL~ and ~VARIABLES~. It also drops ~UNPAGINATE~, ~NOERROR~, ~READER~ (internal functions expect alist-ified JSON) and ~FORGE~ (only Github currently supports GraphQL). ~ghub-graphql~ does not account for the fact that pagination works differently in GraphQL than it does in REST, so users of this function have to deal with that themselves. Likewise error handling works differently and has to be done by the caller too. An early attempt at implementing automatic unpaginating for GraphQL can be found in the ~faithful-graphql~ branch, provided I haven't deleted that by now. On that branch I try to do things as intended by the designers of GraphQL, using variables and fragments, and drowning in a sea of boilerplate. The problem with that approach is that it only works for applications that fetch specific information on demand and actually want things to be paginated. I am convinced that GraphQL is very nice for web apps. However the Forge package for which I have implemented all of this has very different needs. It wants to fetch "all the data" and "cache" it locally, so that it is available even when there is no internet connection. GraphQL was designed around the idea that you should be able to "ask for what you need and get exactly that". But when that boils down to "look, if I persist, then you are going to hand me over all the data anyway, so just caught it up already", then things start to fall apart. If Github's GraphQL allowed pagination to be turned off completely, then teaching ~ghub-graphql~ about error handling would be enough. But it doesn't and when doing things as intended, then that leads to huge amounts of repetitive boilerplate, which is so boring to write that doing it without introducing bugs left and right is near impossible; so I decided to give up on GraphQL variables, fragments and conditions, and instead implement something more powerful, though also more opinionated. - Function: ghub--graphql-vacuum query variables callback &optional until &key narrow username auth host forge :: This function is an opinionated alternative to ~ghub-graphql~. It relies on dark magic to get the job done. It makes an initial request using ~QUERY~. It then looks for paginated edges in the returned data and makes more requests to resolve them. In order to do so it automatically transforms the initial ~QUERY~ into another query suitable for that particular edge. The data retrieved by subsequent requests is then injected into the data of the original request before that is returned or passed to the callback. If subsequently retrieved data features new paginated edges, then those are followed recursively. The end result is essentially the same as using ~ghub-graphql~, if only it were possible to say "do not paginate anything". The implementation is much more complicated because it is not possible to do that. ~QUERY~ is a GraphQL query expressed as an s-expression. The bundled ~gsexp~ library is used to turn that into a GraphQL query string. Only a subset of the GraphQL features are supported; fragments for example are not, and magical stuff happens to variables. This is not documented yet, I am afraid. Look at existing callers. ~VARIABLES~ is a JSON-like alist as for ~ghub-graphql~. ~UNTIL~ is an alist ~((EDGE-until . VALUE)...)~. When unpaginating ~EDGE~ try not to fetch beyond the element whose first field has the value ~VALUE~ and remove that element as well as all "lesser" elements from the retrieved data if necessary. Look at ~forge--pull-repository~ for an example. This is only useful if you "cache" the response locally and want to avoid fetching data again that you already have. Other arguments behave as for ~ghub-graphql~ and ~ghub-request~, more or less. If ~CALLBACK~ is nil, pretty-print the response. Using ~ghub--graphql-vacuum~, the following resource specific functions are implemented. These functions are not part of the public API yet and are very much subject to change. - Function: ghub-fetch-repository owner name callback &optional until &key username auth host forge :: This function asynchronously fetches forge data about the specified repository. Once all data has been collected, ~CALLBACK~ is called with the data as the only argument. - Function: ghub-fetch-issue owner name callback &optional until &key username auth host forge :: This function asynchronously fetches forge data about the specified issue. Once all data has been collected, ~CALLBACK~ is called with the data as the only argument. - Function: ghub-fetch-pullreq owner name callback &optional until &key username auth host forge :: This function asynchronously fetches forge data about the specified pull-request. Once all data has been collected, ~CALLBACK~ is called with the data as the only argument. Note that in order to avoid duplication all of these functions base their initial query on the query stored in ~ghub-fetch-repository~. The latter two pass that query through ~ghub--graphql-prepare-query~, which then uses ~ghub--graphql-narrow-query~ to remove parts the caller is not interested in. These two functions are also used internally, when unpaginating, but as demonstrated here they can be useful even before making an initial request. ** Github Convenience Wrappers - Function: ghub-head resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback :: - Function: ghub-get resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback :: These functions are simple wrappers around ~ghub-request~. Their signature is identical to that of the latter, except that they do not have an argument named ~METHOD~. The HTTP method is instead given by the second word in the function name. As described in the documentation for ~ghub-request~, it depends on the used method whether the value of the ~PARAMS~ argument is used as the query or the payload. For the "HEAD" and "GET" methods it is used as the query. - Function: ghub-put resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback :: - Function: ghub-post resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback :: - Function: ghub-patch resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback :: - Function: ghub-delete resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback :: These functions are simple wrappers around ~ghub-request~. Their signature is identical to that of the latter, except that they do not have an argument named ~METHOD~. The HTTP method is instead given by the second word in the function name. As described in the documentation for ~ghub-request~, it depends on the used method whether the value of the ~PARAMS~ argument is used as the query or the payload. For the "PUT", "POST", "PATCH" and "DELETE" methods it is used as the payload. - Function: ghub-wait resource &optional duration &key username auth host :: Some API requests result in an immediate successful response even when the requested action has not actually been carried out yet. An example is the request for the creation of a new repository, which doesn't cause the repository to immediately become available. The Github API documentation usually mentions this when describing an affected resource. If you want to do something with some resource right after making a request for its creation, then you might have to wait for it to actually be created. This function can be used to do so. It repeatedly tries to access the resource until it becomes available or until a timeout is reached. In the latter case it signals ~ghub-error~. ~RESOURCE~ specifies the resource that this function waits for. ~DURATION~ specifies the maximum number of seconds to wait for, defaulting to 64 seconds. Emacs will block during that time, but the user can abort using ~C-g~. The first attempt is made immediately and will often succeed. If not, then another attempt is made after two seconds, and each subsequent attempt is made after waiting as long as we already waited between all preceding attempts combined. See ~ghub-request~'s documentation above for information about the other arguments. * Notes ** Using Ghub in Personal Scripts You can of course use ~ghub-request~ and its wrapper functions in your personal scripts. Unlike when you use Ghub in a package that you distribute for others to use, you don't have to explicitly specify a package in personal scripts. #+begin_src emacs-lisp ;; This is perfectly acceptable in personal scripts ... (ghub-get "/user") ;; ... and actually equals to (ghub-get "/user" nil :auth 'ghub) ;; In packages you have to specify the package using AUTH. (ghub-get "/user" nil :auth 'some-package) #+end_src When the ~AUTH~ argument is not specified, then a request is made on behalf of the ~ghub~ package itself. Like for any other package you have to create a dedicated token of course. ** Using Ghub in Your Own Package Every package should use its own token. This allows you as the author of some package to only request access to API scopes that are actually needed, which in turn might make it easier for users to trust your package not to do unwanted things. You have to tell ~ghub-request~ on behalf of which package a request is being made by passing the symbol ~PACKAGE~ as the value of its ~AUTH~ argument. #+begin_src emacs-lisp (ghub-request "GET" "/user" nil :auth 'PACKAGE) #+end_src Keep in mind that the users of your package will have to manually create a suitable token. To make that easier, you should not only link to this manual but also prominently mention the scopes the token needs; and explain what they are needed for. ** Forge Limitations and Notes - There are no default Gitea and Gogs instances so the variables ~gitea.host~ and ~gogs.host~ are not taken into account. - Gitea and Gogs do not support limiting a token to certain scopes. - The Bitbucket API is fairly broken and my willingness to deal with that is extremely limited unless someone pays me vast amounts of money. - The Gitlab API documentation is not always accurate, though I don't have an example at hand. It also isn't structured well, making it occasionally difficult to find the information one is looking for. - Where one would use ~user/repo~ when accessing another forge, one has to use ~user%2Frepo~ when accessing Gitlab, e.g.: #+BEGIN_SRC emacs-lisp (ghub-get "/projects/python-mode-devs%2Fpython-mode" nil :forge 'gitlab) #+END_SRC * Function Index :PROPERTIES: :APPENDIX: t :INDEX: fn :END: * Variable Index :PROPERTIES: :APPENDIX: t :INDEX: vr :END: * Copying :PROPERTIES: :COPYING: t :END: #+begin_quote Copyright (C) 2017-{{{year}}} Jonas Bernoulli You can redistribute this document and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. #+end_quote # LocalWords: ARGS AUTH Bitbucket DEFFN DESC ERRORBACK EVAL Auth Ghub Gitea Github # LocalWords: Gitlab Glab Gogs GraphQL LocalWords MERCHANTABILITY # LocalWords: Makefile NOERROR PARAMS # LocalWords: SRC UNPAGINATE alist alists api auth authinfo # LocalWords: backend backends config customizable emacs eval # LocalWords: featurep fn ghub gitea github glab gitlab gogs graphql hostname HTTP JSON # LocalWords: mis netrc noerror num params pullreq repo src texinfo toc # LocalWords: unencrypted unpaginate unpaginating utils vr ziggy # IMPORTANT: Also update ORG_ARGS and ORG_EVAL in the Makefile. # Local Variables: # fill-column: 70 # indent-tabs-mode: nil # org-src-preserve-indentation: nil # sentence-end-double-space: t # End: ghub-5.0.1/docs/ghub.texi000066400000000000000000001056631507100422500152210ustar00rootroot00000000000000\input texinfo @c -*- texinfo -*- @c %**start of header @setfilename ghub.info @settitle Ghub User and Developer Manual @documentencoding UTF-8 @documentlanguage en @c %**end of header @copying @quotation Copyright (C) 2017-2025 Jonas Bernoulli You can redistribute this document and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU General Public License for more details. @end quotation @end copying @dircategory Emacs @direntry * Ghub: (ghub). Client library for the Github API. @end direntry @finalout @titlepage @title Ghub User and Developer Manual @subtitle for version 5.0.1 @author Jonas Bernoulli @page @vskip 0pt plus 1filll @insertcopying @end titlepage @contents @ifnottex @node Top @top Ghub User and Developer Manual Ghub is an Emacs library that is used by various packages to access the APIs of various instances of various Git forge implementations. @noindent This manual is for Ghub version 5.0.1. @insertcopying @end ifnottex @menu * Introduction:: * Getting Started:: * API:: * Notes:: * Function Index:: * Variable Index:: @detailmenu --- The Detailed Node Listing --- Getting Started * Basic Concepts, Arguments and Variables: Basic Concepts Arguments and Variables. * Setting the Username:: * Creating and Storing a Token:: * Github Configuration Variables:: API * Their APIs:: * Making REST Requests:: * Making GraphQL Requests:: * Github Convenience Wrappers:: Notes * Using Ghub in Personal Scripts:: * Using Ghub in Your Own Package:: * Forge Limitations and Notes:: @end detailmenu @end menu @node Introduction @chapter Introduction Ghub is an Emacs library that is used by various packages to access the APIs of various instances of various Git forge implementations. A forge is a web-based collaborative software platform for developing and distributing computer applications. Examples include Github and Gitlab. @node Getting Started @chapter Getting Started This manual guides you through the steps that are necessary to use the Forge package and/or to make a request using just Ghub itself, such as this: @lisp (ghub-request "GET" "/user") @end lisp To be able to do that, Ghub needs to know who you want to talk to, who you are, and how you are going to prove the latter to the former. Additionally Ghub wants to know on behalf of which Emacs package it is making a request. So the question of "who is making the request" has to be rephrased as "which human (or bot) is using what (Emacs) package to make the request". If, for example, the human known as "tarsius" is using the @code{forge} package, then that is represented in some places using the string "tarsius@math{^forge}". @menu * Basic Concepts, Arguments and Variables: Basic Concepts Arguments and Variables. * Setting the Username:: * Creating and Storing a Token:: * Github Configuration Variables:: @end menu @node Basic Concepts Arguments and Variables @section Basic Concepts, Arguments and Variables (If you are trying to configure Forge for @uref{https://github.com} and/or @uref{https://gitlab.com}, then you can skip this section.) Originally Ghub supported only Github but now it also supports Gitlab, Gitea, Gogs and Bitbucket. Because of that, the function @code{ghub-request} defaults to acting on a @code{github} forge, but can be told to act on other forges using the FORGE argument. The FORGE argument only specifies what kind of forge we are accessing, not which host specifically. The HOST argument can be used to select the instance. For some forges a default instance is defined: @itemize @item Forge @code{github} defaults to host @code{api.github.com}. @item Forge @code{gitlab} defaults to host @code{gitlab.com/api/v4}. @item Forge @code{bitbucket} defaults to host @code{api.bitbucket.org/2.0}. @item No canonical host exists for the @code{gitea} and @code{gogs} forges and @code{localhost:3000/api/v1} is used as the default host in both cases. @end itemize Together the FORGE and HOST arguments specify the forge type and instance. In addition to that, it is also necessary to specify on whose behalf the request is being made, which can be done using the USERNAME and AUTH arguments. For example: @lisp (ghub-request "GET" "/user" nil :forge 'github :host "api.github.com" :username "tarsius" :auth 'forge) @end lisp Having to specify these arguments for every request is inconvenient. Additional variables and convenience functions can be used to make that unnecessary in most cases. (But for debugging purposes the above explicit form is very useful. You will obviously have to change the value of USERNAME and you should use @code{ghub} as AUTH when first trying this at home.) These variables can be set globally and/or for a specific repository. @itemize @item For "api.github.com" (aka the API of @uref{https://github.com}) the Git variable @code{github.user} specifies the user. @item For another @code{github} instance the Git variable @code{github.HOST.user} specifies the user. The HOST in that variable name is the same as the value of the HOST argument of the called function. @item Instead of specifying the HOST in every function call, the Git variable @code{github.host} can be used. This should only be set locally. @end itemize These @code{github} specific variables are discussed in more detail in @ref{Github Configuration Variables}. @noindent For @code{gitlab} and @code{bitbucket} forges similar variables are available: @itemize @item @code{gitlab.user} specifies the @uref{https://gitlab.com} user. @item @code{gitlab.HOST.user} specifies the user for the HOST @code{gitlab} instance. @item @code{gitlab.host} specifies the @code{gitlab} host, unless the HOST argument is non-nil @item @code{bitbucket.user} specifies the @uref{https://bitbucket.org} user. @item @code{bitbucket.HOST.user} specifies the user for the HOST @code{bitbucket} instance. @item @code{bitbucket.host} specifies the @code{bitbucket} host, unless the HOST argument is non-nil. @end itemize For the @code{gitea} and @code{gogs} forges some similar variables are available, however for some of the @code{ghub.*} variables no equivalent variable exist for these two forges: @itemize @item @code{gitea.user} is @strong{not} used because no canonical @code{gitea} instance exists. @item @code{gitea.HOST.user} specifies the user for the HOST @code{gitea} instance. @item @code{gitea.host} specifies the @code{gitea} host, unless the HOST argument is non-nil @item @code{gogs.user} is @strong{not} used because no canonical @code{gogs} instance exists. @item @code{gogs.HOST.user} specifies the user for the HOST @code{gogs} instance. @item @code{gogs.host} specifies the @code{gogs} host, unless the HOST argument is non-nil @end itemize @node Setting the Username @section Setting the Username Ghub needs to know your username, which you use on the host that you want it to connect to. For each host a different Git variable has to be set, to specify the username on that host. More than one variable is needed, because you might use different usernames on different hosts. @anchor{Setting your Githubcom Username} @subheading Setting your Github.com Username To inform Ghub about your "github.com" username do this: @example git config --global github.user USERNAME @end example If you need to identify as another user in a particular repository, then you have to set that variable locally: @example cd /path/to/repo git config --local github.user USERNAME @end example @anchor{Setting your Gitlabcom Username} @subheading Setting your Gitlab.com Username To inform Ghub about your "gitlab.com" username do this: @example git config --global gitlab.user USERNAME @end example If you need to identify as another user in a particular repository, then you have to set that variable locally: @example cd /path/to/repo git config --local gitlab.user USERNAME @end example Make sure you use the correct USERNAME for this forge/host. It might not be the same as on "github.com"! @anchor{Setting your Github Enterprise Username} @subheading Setting your Github Enterprise Username For Github Enterprise instances you have to specify where the API can be accessed and a different variable has to be used to set the username. For example if the API is available at @code{https://example.com/api/v3}, then you should do this: @example git config --global github.example.com/api/v3.user USERNAME @end example Make sure you use the correct USERNAME for this instance. It might not be the same as on "github.com"! Doing this only tells Ghub who you are on this host, additionally you have to tell Ghub which repositories are connected to that forge/host, like so: @example cd /path/to/repo git config --local github.host example.com/api/v3 @end example @anchor{Setting your Username for Other Hosts and/or Forges} @subheading Setting your Username for Other Hosts and/or Forges To inform Ghub about your username on HOST (a FORGE instance) do this: @example git config --global FORGE.HOST.user USERNAME @end example FORGE can be one of @code{bitbucket}, @code{gitea} or @code{gogs}. It can also be @code{github} or @code{gitlab}; but if that is the case, then you should look at the preceding sections instead, which discuss these cases specifically. HOST identifies the instance. This actually points at the top-level endpoint of the API and may contain path components, e.g.: @code{example.com/api}. If you need to identify as another user in a particular repository, then you have to set that variable locally: @example cd /path/to/repo git config --local FORGE.HOST.user USERNAME @end example @node Creating and Storing a Token @section Creating and Storing a Token @anchor{Creating a Token} @subsection Creating a Token To create a token, use the web interface of the host you want to connect to. Here is a list of pages to do this for certain popular hosts: @itemize @item @uref{https://github.com/settings/tokens} @item @uref{https://gitlab.com/-/user_settings/personal_access_tokens} @end itemize For other forges we cannot provide a functioning URL because they contain unknown values such as your name. Just go to the general settings page of the respective host and then go from there. Except on @code{gitea} and @code{gogs} each token can be limited to certain "scopes", i.e., it is possible to limit for which purposes any given token can be used. Before you create a token to be used for a certain package, you should consult the documentation of that package, which in turn should tell you which scopes are needed and why. The Forge package for example does so in @ref{Token Creation,,,forge,}. @anchor{Storing a Token} @subsection Storing a Token Please also see @ref{Top,,,auth,} for all the gory details about Auth-Source. The variable @code{auth-sources} controls how and where Auth-Source keeps its secrets. The default value is a list of three files: @code{("~/.authinfo" "~/.authinfo.gpg" "~/.netrc")}, but to avoid confusion you should make sure that only one of these files exists, and then you should also adjust the value of the variable to only ever use that file, for example: @lisp (setq auth-sources '("~/.authinfo")) @end lisp In @code{~/.authinfo} secrets are stored in plain text. If you don't want that, then you should use the encrypted @code{~/.authinfo.gpg} instead: @lisp (setq auth-sources '("~/.authinfo.gpg")) @end lisp Auth-Source also supports storing secrets in various external key-chains. See @ref{Top,,,auth,} for more information. The default Auth-Source backends only support storing three values per entry; the "machine", the "login" and the "password". Because Ghub uses separate tokens for each package, it has to squeeze four values into those three slots, and it does that by using "USERNAME@math{^PACKAGE}" as the "login". Assuming your @strong{Github} username is "ziggy", the package is named "forge", and you want to access @strong{Github.com} with the @strong{token} "012345abcdef@dots{}", an entry in one of the three mentioned files would then look like this: @example machine api.github.com login ziggy^forge password 012345abcdef... @end example Assuming your @strong{Gitlab} username is "ziggy", the package is named "forge", and you want to access @strong{Gitlab.com} with the @strong{token} "012345abcdef@dots{}", an entry in one of the three mentioned files would then look like this: @example machine gitlab.com/api/v4 login ziggy^forge password 012345abcdef... @end example @node Github Configuration Variables @section Github Configuration Variables The username and, unless you only use Github.com itself, the Github Enterprise instance have to be configured using Git variables. In rare cases it might also be necessary to specify the identity of the local machine, which is done using a lisp variable. @defvar github.user The Github.com username. This should be set globally and if you have multiple Github.com user accounts, then you should set this locally only for those repositories that you want to access using the secondary identity. @end defvar @defvar github.HOST.user This variable serves the same purpose as @code{github.user} but for the Github Enterprise instance identified by @code{HOST}. The reason why separate variables are used is that this makes it possible to set both values globally instead of having to set one of the values locally in each and every repository that is connected to the Github Enterprise instance, not Github.com. @end defvar @defvar github.host This variable should only be set locally for a repository and specifies the Github Enterprise edition that that repository is connected to. You should not set this globally because then each and every repository becomes connected to the specified Github Enterprise instance, including those that should actually be connected to Github.com. When this is undefined, then "api.github.com" is used (defined in the constant @code{ghub-default-host}, which you should never attempt to change.) @end defvar @node API @chapter API @menu * Their APIs:: * Making REST Requests:: * Making GraphQL Requests:: * Github Convenience Wrappers:: @end menu @node Their APIs @section Their APIs Of course this manual does not cover the APIs of all forges that it supports, but for your convenience, here are the links to their API manuals: @itemize @item Github: @itemize @item @uref{https://docs.github.com/en/graphql} (GraphQl) @item @uref{https://docs.github.com/en/rest} (REST) @end itemize @item Gitlab: @itemize @item @uref{https://docs.gitlab.com/api} @end itemize @item Gitea: @itemize @item @uref{https://docs.gitea.com/next/development/api-usage} @item @uref{https://demo.gitea.com} @end itemize @item Gogs: @itemize @item @uref{https://gogs.io/docs} @end itemize @item Bitbucket: @itemize @item @uref{https://developer.atlassian.com/cloud/bitbucket} @end itemize @end itemize @node Making REST Requests @section Making REST Requests @defun ghub-request method resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback url value error extra method* This function makes a request for @code{RESOURCE} using @code{METHOD}. @code{PARAMS}, @code{QUERY}, @code{PAYLOAD} and/or @code{HEADERS} are alists holding additional request data. The response body is returned and the response headers are stored in the variable @code{ghub-response-headers}. @itemize @item @code{METHOD} is the HTTP method, given as a string. @item @code{RESOURCE} is the resource to access, given as a string beginning with a slash. @item @code{PARAMS}, @code{QUERY}, @code{PAYLOAD} and @code{HEADERS} are alists and are used to specify request data. All these arguments are alists that resemble the JSON expected and returned by the Github API@. The keys are symbols and the values stored in the @code{cdr} (not the @code{cadr}) can be strings, integers, or lists of strings and integers. The Github API documentation is vague on how data has to be transmitted and for a particular resource usually just talks about "parameters". Generally speaking when the @code{METHOD} is "HEAD" or "GET", then they have to be transmitted as a query, otherwise as a payload. @itemize @item Use @code{PARAMS} to automatically transmit like @code{QUERY} or @code{PAYLOAD} would depending on @code{METHOD}. @item Use @code{QUERY} to explicitly transmit data as a query. @item Use @code{PAYLOAD} to explicitly transmit data as a payload. Instead of an alist, @code{PAYLOAD} may also be a string, in which case it gets encoded as UTF-8 but is otherwise transmitted as-is. @item Use @code{HEADERS} for those rare resources that require that the data is transmitted as headers instead of as a query or payload. When that is the case, then the Github API documentation usually mentions it explicitly. @end itemize @item If @code{SILENT} is non-nil, then progress reports and the like are not messaged. @item If @code{UNPAGINATE} is t, then this function makes as many requests as necessary to get all values. If @code{UNPAGINATE} is a natural number, then it gets at most that many pages. For any other non-nil value it raises an error. @item If @code{NOERROR} is non-nil, then no error is raised if the request fails and @code{nil} is returned instead. If @code{NOERROR} is @code{return}, then the error payload is returned instead of @code{nil}. @item If @code{READER} is non-nil, then it is used to read and return from the response buffer. The default is @code{ghub--read-json-payload}. For the very few resources that do not return JSON, you might want to use @code{ghub--decode-payload}. @item If @code{USERNAME} is non-nil, then the request is made on behalf of that user. It is better to specify the user using the Git variable @code{github.user} for "api.github.com", or @code{github.HOST.user} if connecting to a Github Enterprise instance. @item Each package that uses Ghub should use its own token. If @code{AUTH} is @code{nil} or unspecified, then the generic @code{ghub} token is used instead. This is only acceptable for personal utilities. A package that is distributed to other users should always use this argument to identify itself, using a symbol matching its name. Package authors who find this inconvenient should write a wrapper around this function and possibly for the method-specific functions as well. Beside @code{nil}, some other symbols have a special meaning too. @code{none} means to make an unauthorized request. @code{basic} means to make a password based request. If the value is a string, then it is assumed to be a valid token. @code{basic} and an explicit token string are only intended for internal and debugging uses. If @code{AUTH} is a package symbol, then the scopes are specified using the variable @code{AUTH-github-token-scopes}. It is an error if that is not specified. See @code{ghub-github-token-scopes} for an example. @item If @code{HOST} is non-nil, then connect to that Github instance. This defaults to "api.github.com". When a repository is connected to a Github Enterprise instance, then it is better to specify that using the Git variable @code{github.host} instead of using this argument. @item If @code{FORGE} is @code{gitlab}, then connect to Gitlab.com or, depending on @code{HOST}, to another Gitlab instance. @item If @code{CALLBACK} and/or @code{ERRORBACK} is non-nil, then this function makes one or more asynchronous requests and calls @code{CALLBACK} or @code{ERRORBACK} when finished. If no error occurred, then it calls @code{CALLBACK}, unless that is @code{nil}. If an error occurred, then it calls @code{ERRORBACK}, or if that is nil, then @code{CALLBACK}. @code{ERRORBACK} can also be @code{t}, in which case it signals instead. @code{NOERROR} is ignored for all asynchronous requests. Both callbacks are called with four arguments. @enumerate @item For @code{CALLBACK}, the combined value of the retrieved pages. For @code{ERRORBACK}, the error that occurred when retrieving the last page. @item The headers of the last page as an alist. @item Status information provided by @code{url-retrieve}. Its @code{:error} property holds the same information as the first argument to @code{ERRORBACK}. @item A @code{ghub--req} struct, which can be passed to @code{ghub-continue} (which see) to retrieve the next page, if any. @end enumerate @end itemize @end defun @defun ghub-continue args If there is a next page, then this function retrieves that. This function is only intended to be called from callbacks. If there is a next page, then that is retrieved and the buffer that the result will be loaded into is returned, or t if the process has already completed. If there is no next page, then return nil. Callbacks are called with four arguments (see @code{ghub-request}). The forth argument is a @code{ghub--req} struct, intended to be passed to this function. A callback may use the struct's @code{extra} slot to pass additional information to the callback that will be called after the next request. Use the function @code{ghub-req-extra} to get and set the value of that slot. As an example, using @code{ghub-continue} in a callback like so: @lisp (ghub-get "/users/tarsius/repos" nil :callback (lambda (value _headers _status req) (unless (ghub-continue req) (setq my-value value)))) @end lisp is equivalent to: @lisp (ghub-get "/users/tarsius/repos" nil :unpaginate t :callback (lambda (value _headers _status _req) (setq my-value value))) @end lisp To demonstrate how to pass information from one callback to the next, here we record when we start fetching each page: @lisp (ghub-get "/users/tarsius/repos" nil :extra (list (current-time)) :callback (lambda (value _headers _status req) (push (current-time) (ghub-req-extra req)) (unless (ghub-continue req) (setq my-times (ghub-req-extra req)) (setq my-value value)))) @end lisp @end defun @defvar ghub-response-headers A select few Github API resources respond by transmitting data in the response header instead of in the response body. Because there are so few of these inconsistencies, @code{ghub-request} always returns the response body. To access the response headers use this variable after @code{ghub-request} has returned. @end defvar @defun ghub-response-link-relations req headers payload This function returns an alist of the link relations in @code{HEADERS}, or if optional @code{HEADERS} is nil, then those in @code{ghub-response-headers}. When accessing a Bitbucket instance then the link relations are in @code{PAYLOAD} instead of @code{HEADERS}, making their API merely RESTish and forcing this function to append those relations to the value of @code{ghub-response-headers}, for later use when this function is called with @code{nil} for @code{PAYLOAD}. @end defun @node Making GraphQL Requests @section Making GraphQL Requests @defun ghub-graphql graphql &optional variables &key username auth host callback silent callback errorback value extra This function makes a GraphQL request using @code{GRAPHQL} and @code{VARIABLES} as inputs. @code{GRAPHQL} is a GraphQL string. @code{VARIABLES} is a JSON-like alist. The other arguments behave as for @code{ghub-request} (which see). The response is returned as a JSON-like alist. Even if the response contains @code{errors}, this function does not raise an error. Cursor-handling is likewise left to the caller. @end defun @code{ghub-graphql} is a thin convenience wrapper around @code{ghub-request}, similar to @code{ghub-post} and friends. While the latter only hard-code the value of the @code{METHOD} argument, the former also hard-codes @code{RESOURCE} and constructs @code{PAYLOAD} from @code{GRAPHQL} and @code{VARIABLES}. It also drops @code{UNPAGINATE}, @code{NOERROR}, @code{READER} (internal functions expect alist-ified JSON) and @code{FORGE} (only Github currently supports GraphQL). @code{ghub-graphql} does not account for the fact that pagination works differently in GraphQL than it does in REST, so users of this function have to deal with that themselves. Likewise error handling works differently and has to be done by the caller too. An early attempt at implementing automatic unpaginating for GraphQL can be found in the @code{faithful-graphql} branch, provided I haven't deleted that by now. On that branch I try to do things as intended by the designers of GraphQL, using variables and fragments, and drowning in a sea of boilerplate. The problem with that approach is that it only works for applications that fetch specific information on demand and actually want things to be paginated. I am convinced that GraphQL is very nice for web apps. However the Forge package for which I have implemented all of this has very different needs. It wants to fetch "all the data" and "cache" it locally, so that it is available even when there is no internet connection. GraphQL was designed around the idea that you should be able to "ask for what you need and get exactly that". But when that boils down to "look, if I persist, then you are going to hand me over all the data anyway, so just caught it up already", then things start to fall apart. If Github's GraphQL allowed pagination to be turned off completely, then teaching @code{ghub-graphql} about error handling would be enough. But it doesn't and when doing things as intended, then that leads to huge amounts of repetitive boilerplate, which is so boring to write that doing it without introducing bugs left and right is near impossible; so I decided to give up on GraphQL variables, fragments and conditions, and instead implement something more powerful, though also more opinionated. @defun ghub--graphql-vacuum query variables callback &optional until &key narrow username auth host forge This function is an opinionated alternative to @code{ghub-graphql}. It relies on dark magic to get the job done. It makes an initial request using @code{QUERY}. It then looks for paginated edges in the returned data and makes more requests to resolve them. In order to do so it automatically transforms the initial @code{QUERY} into another query suitable for that particular edge. The data retrieved by subsequent requests is then injected into the data of the original request before that is returned or passed to the callback. If subsequently retrieved data features new paginated edges, then those are followed recursively. The end result is essentially the same as using @code{ghub-graphql}, if only it were possible to say "do not paginate anything". The implementation is much more complicated because it is not possible to do that. @code{QUERY} is a GraphQL query expressed as an s-expression. The bundled @code{gsexp} library is used to turn that into a GraphQL query string. Only a subset of the GraphQL features are supported; fragments for example are not, and magical stuff happens to variables. This is not documented yet, I am afraid. Look at existing callers. @code{VARIABLES} is a JSON-like alist as for @code{ghub-graphql}. @code{UNTIL} is an alist @code{((EDGE-until . VALUE)...)}. When unpaginating @code{EDGE} try not to fetch beyond the element whose first field has the value @code{VALUE} and remove that element as well as all "lesser" elements from the retrieved data if necessary. Look at @code{forge--pull-repository} for an example. This is only useful if you "cache" the response locally and want to avoid fetching data again that you already have. Other arguments behave as for @code{ghub-graphql} and @code{ghub-request}, more or less. If @code{CALLBACK} is nil, pretty-print the response. @end defun Using @code{ghub--graphql-vacuum}, the following resource specific functions are implemented. These functions are not part of the public API yet and are very much subject to change. @defun ghub-fetch-repository owner name callback &optional until &key username auth host forge This function asynchronously fetches forge data about the specified repository. Once all data has been collected, @code{CALLBACK} is called with the data as the only argument. @end defun @defun ghub-fetch-issue owner name callback &optional until &key username auth host forge This function asynchronously fetches forge data about the specified issue. Once all data has been collected, @code{CALLBACK} is called with the data as the only argument. @end defun @defun ghub-fetch-pullreq owner name callback &optional until &key username auth host forge This function asynchronously fetches forge data about the specified pull-request. Once all data has been collected, @code{CALLBACK} is called with the data as the only argument. @end defun Note that in order to avoid duplication all of these functions base their initial query on the query stored in @code{ghub-fetch-repository}. The latter two pass that query through @code{ghub--graphql-prepare-query}, which then uses @code{ghub--graphql-narrow-query} to remove parts the caller is not interested in. These two functions are also used internally, when unpaginating, but as demonstrated here they can be useful even before making an initial request. @node Github Convenience Wrappers @section Github Convenience Wrappers @defun ghub-head resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback @end defun @defun ghub-get resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback These functions are simple wrappers around @code{ghub-request}. Their signature is identical to that of the latter, except that they do not have an argument named @code{METHOD}. The HTTP method is instead given by the second word in the function name. As described in the documentation for @code{ghub-request}, it depends on the used method whether the value of the @code{PARAMS} argument is used as the query or the payload. For the "HEAD" and "GET" methods it is used as the query. @end defun @defun ghub-put resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback @end defun @defun ghub-post resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback @end defun @defun ghub-patch resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback @end defun @defun ghub-delete resource &optional params &key query payload headers unpaginate noerror reader username auth host callback errorback These functions are simple wrappers around @code{ghub-request}. Their signature is identical to that of the latter, except that they do not have an argument named @code{METHOD}. The HTTP method is instead given by the second word in the function name. As described in the documentation for @code{ghub-request}, it depends on the used method whether the value of the @code{PARAMS} argument is used as the query or the payload. For the "PUT", "POST", "PATCH" and "DELETE" methods it is used as the payload. @end defun @defun ghub-wait resource &optional duration &key username auth host Some API requests result in an immediate successful response even when the requested action has not actually been carried out yet. An example is the request for the creation of a new repository, which doesn't cause the repository to immediately become available. The Github API documentation usually mentions this when describing an affected resource. If you want to do something with some resource right after making a request for its creation, then you might have to wait for it to actually be created. This function can be used to do so. It repeatedly tries to access the resource until it becomes available or until a timeout is reached. In the latter case it signals @code{ghub-error}. @code{RESOURCE} specifies the resource that this function waits for. @code{DURATION} specifies the maximum number of seconds to wait for, defaulting to 64 seconds. Emacs will block during that time, but the user can abort using @code{C-g}. The first attempt is made immediately and will often succeed. If not, then another attempt is made after two seconds, and each subsequent attempt is made after waiting as long as we already waited between all preceding attempts combined. See @code{ghub-request}'s documentation above for information about the other arguments. @end defun @node Notes @chapter Notes @menu * Using Ghub in Personal Scripts:: * Using Ghub in Your Own Package:: * Forge Limitations and Notes:: @end menu @node Using Ghub in Personal Scripts @section Using Ghub in Personal Scripts You can of course use @code{ghub-request} and its wrapper functions in your personal scripts. Unlike when you use Ghub in a package that you distribute for others to use, you don't have to explicitly specify a package in personal scripts. @lisp ;; This is perfectly acceptable in personal scripts ... (ghub-get "/user") ;; ... and actually equals to (ghub-get "/user" nil :auth 'ghub) ;; In packages you have to specify the package using AUTH. (ghub-get "/user" nil :auth 'some-package) @end lisp When the @code{AUTH} argument is not specified, then a request is made on behalf of the @code{ghub} package itself. Like for any other package you have to create a dedicated token of course. @node Using Ghub in Your Own Package @section Using Ghub in Your Own Package Every package should use its own token. This allows you as the author of some package to only request access to API scopes that are actually needed, which in turn might make it easier for users to trust your package not to do unwanted things. You have to tell @code{ghub-request} on behalf of which package a request is being made by passing the symbol @code{PACKAGE} as the value of its @code{AUTH} argument. @lisp (ghub-request "GET" "/user" nil :auth 'PACKAGE) @end lisp Keep in mind that the users of your package will have to manually create a suitable token. To make that easier, you should not only link to this manual but also prominently mention the scopes the token needs; and explain what they are needed for. @node Forge Limitations and Notes @section Forge Limitations and Notes @itemize @item There are no default Gitea and Gogs instances so the variables @code{gitea.host} and @code{gogs.host} are not taken into account. @item Gitea and Gogs do not support limiting a token to certain scopes. @item The Bitbucket API is fairly broken and my willingness to deal with that is extremely limited unless someone pays me vast amounts of money. @item The Gitlab API documentation is not always accurate, though I don't have an example at hand. It also isn't structured well, making it occasionally difficult to find the information one is looking for. @item Where one would use @code{user/repo} when accessing another forge, one has to use @code{user%2Frepo} when accessing Gitlab, e.g.: @lisp (ghub-get "/projects/python-mode-devs%2Fpython-mode" nil :forge 'gitlab) @end lisp @end itemize @node Function Index @appendix Function Index @printindex fn @node Variable Index @appendix Variable Index @printindex vr @bye ghub-5.0.1/docs/htmlxref.cnf000066400000000000000000000005621507100422500157120ustar00rootroot00000000000000EMACS = https://www.gnu.org/software/emacs/manual auth mono ${EMACS}/html_mono/auth.html auth node ${EMACS}/html_node/auth/ ediff mono ${EMACS}/html_mono/ediff.html ediff node ${EMACS}/html_node/ediff/ elisp mono ${EMACS}/html_mono/elisp.html elisp node ${EMACS}/html_node/elisp/ emacs mono ${EMACS}/html_mono/emacs.html emacs node ${EMACS}/html_node/emacs/ ghub-5.0.1/lisp/000077500000000000000000000000001507100422500134055ustar00rootroot00000000000000ghub-5.0.1/lisp/Makefile000066400000000000000000000023761507100422500150550ustar00rootroot00000000000000-include ../config.mk include ../default.mk lisp: $(ELCS) loaddefs check-declare loaddefs: $(PKG)-autoloads.el ghub.elc: gsexp.elc: ghub-graphql.elc: ghub.elc gsexp.elc ghub-legacy.elc: ghub.elc gsexp.elc ghub-graphql.elc %.elc: %.el @printf "Compiling $<\n" @$(EMACS) -Q --batch $(EMACS_ARGS) $(LOAD_PATH) -f batch-byte-compile $< check-declare: @printf " Checking function declarations\n" @$(EMACS) -Q --batch $(EMACS_ARGS) $(LOAD_PATH) \ --eval "(check-declare-directory default-directory)" CLEAN = $(ELCS) $(PKG)-autoloads.el clean: @printf " Cleaning lisp/*...\n" @rm -rf $(CLEAN) $(PKG)-autoloads.el: $(ELS) @printf " Creating $@\n" @$(EMACS) -Q --batch -l autoload -l cl-lib --eval "\ (let ((file (expand-file-name \"$@\"))\ (autoload-timestamps nil) \ (backup-inhibited t)\ (version-control 'never)\ (coding-system-for-write 'utf-8-emacs-unix))\ (write-region (autoload-rubric file \"package\" nil) nil file nil 'silent)\ (cl-letf (((symbol-function 'progress-reporter-do-update) (lambda (&rest _)))\ ((symbol-function 'progress-reporter-done) (lambda (_))))\ (let ((generated-autoload-file file))\ (update-directory-autoloads default-directory))))" \ 2>&1 | sed "/^Package autoload is deprecated$$/d" ghub-5.0.1/lisp/ghub-graphql.el000066400000000000000000000330361507100422500163150ustar00rootroot00000000000000;;; ghub-graphql.el --- Access Github API using GraphQL -*- lexical-binding:t -*- ;; Copyright (C) 2016-2025 Jonas Bernoulli ;; Author: Jonas Bernoulli ;; Homepage: https://github.com/magit/ghub ;; Keywords: tools ;; SPDX-License-Identifier: GPL-3.0-or-later ;; This file is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published ;; by the Free Software Foundation, either version 3 of the License, ;; or (at your option) any later version. ;; ;; This file is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; ;; You should have received a copy of the GNU General Public License ;; along with this file. If not, see . ;;; Commentary: ;; This library implements GraphQL queries for Github. ;;; Code: (require 'ghub) (require 'gsexp) (require 'treepy) (eval-when-compile (require 'subr-x)) (define-error 'ghub-graphql-error "GraphQL Error" 'ghub-error) (defvar ghub-graphql-message-progress nil "Whether to show \"Fetching page N...\" in echo area during requests. By default this information is only shown in the mode-line of the buffer from which the request was initiated, and if you kill that buffer, then nowhere. That may make it desirable to display the same message in the echo area as well.") (defvar ghub-graphql-items-per-request 50 "Number of GraphQL items to query for entities that return a collection. Adjust this value if you're hitting query timeouts against larger repositories.") (cl-defun ghub-graphql-rate-limit (&key username auth host) "Return rate limit information." (let-alist (ghub-query '(query (rateLimit limit cost remaining resetAt)) nil :synchronous t :username username :auth auth :host host) .data.rateLimit)) (cl-defstruct (ghub--graphql-req (:include ghub--req) (:constructor ghub--make-graphql-req) (:copier nil)) (query nil :read-only t) (query-str nil :read-only nil) (variables nil :read-only t) (until nil :read-only t) (pages 0 :read-only nil) (paginate nil :read-only nil) (narrow nil :read-only t)) (cl-defun ghub-query (query &optional variables &key until narrow headers paginate callback errorback noerror synchronous username auth host forge) (declare (indent defun)) (unless forge (setq forge 'github)) (unless host (setq host (ghub--host forge))) (unless (or username (stringp auth) (eq auth 'none)) (setq username (ghub--username host forge))) (when (eq callback 'pp) (setq callback #'ghub--graphql-pp-response) (setq noerror t)) (ghub--graphql-retrieve (ghub--make-graphql-req :url (ghub--encode-url host (if (eq forge 'gitlab) "/api/graphql" "/graphql")) :method "POST" :headers (ghub--headers headers host auth username forge) :handler #'ghub--graphql-handle-response :query query :variables variables :until until :buffer (current-buffer) :narrow narrow :paginate (or paginate (and-let* ((p (and (eq auth 'forge) (fboundp 'magit-get) (magit-get "forge.graphqlItemLimit")))) (string-to-number p))) :noerror noerror :synchronous synchronous :callback callback :errorback errorback))) (cl-defun ghub--graphql-retrieve (req &optional lineage cursor) (let ((p (cl-incf (ghub--graphql-req-pages req)))) (when (> p 1) (when ghub-graphql-message-progress (let ((message-log-max nil)) (message "Fetching page %s..." p))) (ghub--graphql-set-mode-line req "Fetching page %s" p))) (setf (ghub--graphql-req-query-str req) (gsexp-encode (ghub--graphql-prepare-query (ghub--graphql-req-query req) lineage cursor))) (when ghub-debug (with-current-buffer (get-buffer-create " *gsexp-encode*") (erase-buffer) (insert (ghub--graphql-req-query-str req) "\n\n") (let ((pos (point))) (insert (ghub--encode-payload (ghub--graphql-req-variables req)) "\n") (ignore-errors (json-pretty-print pos (point)))))) (ghub--retrieve (ghub--encode-payload `((query . ,(ghub--graphql-req-query-str req)) ,@(and-let* ((variables (ghub--graphql-req-variables req))) `((variables . ,variables))))) req) (ghub--req-value req)) (defun ghub--graphql-prepare-query (query &optional lineage cursor paginate) (when lineage (setq query (ghub--graphql-narrow-query query lineage cursor))) (let ((loc (ghub--alist-zip query)) variables) (catch :done (while t (let ((node (treepy-node loc))) (when (and (vectorp node) (listp (aref node 0))) (let ((alist (append node ())) (vars nil)) (when-let ((edges (cadr (assq :edges alist)))) (push (list 'first (apply #'min (delq nil (list (and (numberp edges) edges) paginate ghub-graphql-items-per-request)))) vars) (setq loc (treepy-up loc)) (setq node (treepy-node loc)) (setq loc (treepy-replace loc `(,(car node) ,(cadr node) (pageInfo endCursor hasNextPage) (edges (node ,@(cddr node)))))) (setq loc (treepy-down loc)) (setq loc (treepy-next loc))) (dolist (elt alist) (cond ((keywordp (car elt))) ((length= elt 3) (push (list (nth 0 elt) (nth 1 elt)) vars) (push (list (nth 1 elt) (nth 2 elt)) variables)) ((length= elt 2) (push elt vars)))) (setq loc (treepy-replace loc (vconcat (nreverse vars))))))) (if (treepy-end-p loc) (let ((node (copy-sequence (treepy-node loc)))) (when variables (push (vconcat (nreverse variables)) (cdr node))) (throw :done node)) (setq loc (treepy-next loc))))))) (defun ghub--graphql-handle-response (status req) (let ((buf (current-buffer))) (unwind-protect (progn (set-buffer-multibyte t) (let* ((headers (ghub--handle-response-headers status req)) (payload (ghub--handle-response-payload req)) (err (plist-get status :error)) (errors (and (not (and (ghub--req-noerror req) (assq 'data payload))) (assq 'errors payload)))) (cond ((or err errors) (when (and (not err) ghub-debug) (ignore-errors (json-pretty-print (point) (point-max))) (pop-to-buffer buf)) (ghub--graphql-handle-failure req (or err errors) headers status)) ((ghub--graphql-walk-response req (assq 'data payload)))))) (when (and (buffer-live-p buf) (not (buffer-local-value 'ghub-debug buf))) (kill-buffer buf))))) (defun ghub--graphql-handle-failure (req errors headers status) (ghub--graphql-set-mode-line req) (setf (ghub--req-value req) errors) (if-let ((errorback (ghub--req-errorback req))) (ghub--graphql-run-callback req errorback errors headers status req) (if (ghub--req-noerror req) (when-let ((callback (ghub--req-callback req))) (ghub--graphql-run-callback req callback errors)) (ghub--signal-error (if (eq (car errors) 'errors) (cons 'ghub-graphql-error (cdr errors)) errors))))) (defun ghub--graphql-handle-success (req data) (ghub--graphql-set-mode-line req) (when-let ((narrow (ghub--graphql-req-narrow req))) (while-let ((key (pop narrow))) (setq data (cdr (assq key data))))) (setf (ghub--req-value req) data) (when-let ((callback (ghub--req-callback req))) (ghub--graphql-run-callback req callback data))) (defun ghub--graphql-run-callback (req callback &rest args) (let ((buffer (ghub--req-buffer req))) (if (buffer-live-p buffer) (with-current-buffer buffer (apply callback args)) (apply callback args)))) (defun ghub--graphql-set-mode-line (req &optional format &rest args) (let ((buffer (ghub--graphql-req-buffer req))) (when (buffer-live-p buffer) (with-current-buffer buffer (setq mode-line-process (and format (concat " " (apply #'format format args)))) (force-mode-line-update t))))) (defun ghub--graphql-pp-response (data) (pp-display-expression data "*Pp Eval Output*")) (defun ghub--graphql-walk-response (req data) (let* ((loc (ghub--req-value req)) (loc (if (not loc) (ghub--alist-zip data) (setq data (ghub--graphql-narrow-data data (ghub--graphql-lineage loc))) (setf (alist-get 'edges data) (append (alist-get 'edges (treepy-node loc)) (or (alist-get 'edges data) (error "BUG: Expected new nodes")))) (treepy-replace loc data)))) (catch :done (while t (when (eq (car-safe (treepy-node loc)) 'edges) (setq loc (treepy-up loc)) (pcase-let ((`(,key . ,val) (treepy-node loc))) (let-alist val (let* ((cursor (and .pageInfo.hasNextPage .pageInfo.endCursor)) (until (cdr (assq (intern (format "%s-until" key)) (ghub--graphql-req-until req)))) (nodes (mapcar #'cdar .edges)) (nodes (if until (seq-take-while (lambda (node) (or (string> (cdr (assq 'updatedAt node)) until) (setq cursor nil))) nodes) nodes))) (cond (cursor (setf (ghub--req-value req) loc) (ghub--graphql-retrieve req (ghub--graphql-lineage loc) cursor) (throw :done nil)) ((setq loc (treepy-replace loc (cons key nodes))))))))) (if (treepy-end-p loc) (progn (ghub--graphql-handle-success req (treepy-root loc)) (throw :done nil)) (setq loc (treepy-next loc))))))) (defun ghub--graphql-lineage (loc) (let (lineage) (while (treepy-up loc) (push (car (treepy-node loc)) lineage) (setq loc (treepy-up loc))) lineage)) (defun ghub--graphql-narrow-data (data lineage) (while-let ((key (pop lineage))) (if (consp (car lineage)) (progn (pop lineage) (setf data (cadr data))) (setq data (assq key (cdr data))))) data) (defun ghub--graphql-narrow-query (query lineage &optional cursor) (if (consp (car lineage)) (let* ((child (cddr query)) (alist (append (cadr query) ())) (single (cdr (assq :singular alist)))) `(,(car single) ,(vector (list (cadr single) (cdr (car lineage)))) ,@(if (cdr lineage) (ghub--graphql-narrow-query child (cdr lineage) cursor) child))) (let* ((child (or (assq (car lineage) (cdr query)) ;; Alias (cl-find-if (lambda (c) (eq (car-safe (car-safe c)) (car lineage))) query) ;; Edges (cl-find-if (lambda (c) (and (listp c) (vectorp (cadr c)) (eq (cadr (assq :singular (append (cadr c) ()))) (car lineage)))) (cdr query)) (error "BUG: Failed to narrow query"))) (object (car query)) (args (and (vectorp (cadr query)) (cadr query)))) `(,object ,@(and args (list args)) ,(cond ((cdr lineage) (ghub--graphql-narrow-query child (cdr lineage) cursor)) (cursor `(,(car child) ,(vconcat `((after ,cursor)) (cadr child)) ,@(cddr child))) (t child)))))) (defun ghub--alist-zip (root) (let ((branchp (##and (listp %) (listp (cdr %)))) (make-node (lambda (_ children) children))) (treepy-zipper branchp #'identity make-node root))) ;;; _ (provide 'ghub-graphql) ;;; ghub-graphql.el ends here ghub-5.0.1/lisp/ghub-legacy.el000066400000000000000000000335601507100422500161250ustar00rootroot00000000000000;;; ghub-legacy.el --- Deprecated Ghub functions -*- lexical-binding:t -*- ;; Copyright (C) 2016-2025 Jonas Bernoulli ;; Author: Jonas Bernoulli ;; Homepage: https://github.com/magit/ghub ;; Keywords: tools ;; SPDX-License-Identifier: GPL-3.0-or-later ;; This file is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published ;; by the Free Software Foundation, either version 3 of the License, ;; or (at your option) any later version. ;; ;; This file is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; ;; You should have received a copy of the GNU General Public License ;; along with this file. If not, see . ;;; Commentary: ;; Deprecated Ghub functions. ;;; Code: (require 'ghub-graphql) (cl-defun ghub-graphql (graphql &optional variables &key username auth host forge headers silent callback errorback value extra) (cl-assert (not (stringp variables))) (cl-assert (or (stringp graphql) (memq (car-safe graphql) '(query mutation)))) (unless (stringp graphql) (setq graphql (gsexp-encode (ghub--graphql-prepare-query graphql)))) (ghub-request "POST" (if (eq forge 'gitlab) "/api/graphql" "/graphql") nil :payload `((query . ,graphql) ,@(and variables `((variables ,@variables)))) :headers headers :silent silent :username username :auth auth :host host :forge forge :callback callback :errorback errorback :extra extra :value value)) (cl-defun ghub--graphql (graphql &optional variables &key username auth host forge headers callback errorback) (ghub--graphql-vacuum graphql variables callback nil :username username :auth auth :host host :forge forge :headers headers :errorback errorback)) (cl-defun ghub--graphql-vacuum ( query variables callback &optional until &key narrow username auth host forge headers paginate errorback noerror synchronous) (ghub-query query variables :until until :narrow narrow :headers headers :paginate paginate :callback callback :errorback errorback :noerror noerror :synchronous synchronous :username username :auth auth :host host :forge forge)) (defconst ghub-fetch-repository-sparse '(query (repository [(owner $owner String!) (name $name String!)] name id createdAt updatedAt nameWithOwner (parent nameWithOwner) description homepageUrl (defaultBranchRef name) isArchived isFork isLocked isMirror isPrivate hasDiscussionsEnabled hasIssuesEnabled hasWikiEnabled (licenseInfo name) (stargazers totalCount) (watchers totalCount)))) (defconst ghub-fetch-repository `(query (repository ,@(cdr (cadr ghub-fetch-repository-sparse)) (assignableUsers [(:edges t)] id login name) (discussionCategories [(:edges t)] id name emoji isAnswerable description) (discussions [(:edges t) (:singular discussion number) (orderBy ((field UPDATED_AT) (direction DESC)))] id databaseId number url stateReason ;; Discussions lack isReadByViewer. (answer id) (author login) title createdAt updatedAt closedAt locked (category id) body (comments [(:edges t)] id databaseId (author login) createdAt updatedAt body (replies [(:edges 20)] id databaseId (author login) createdAt updatedAt body)) (labels [(:edges t)] id)) (issues [(:edges t) (:singular issue number) (orderBy ((field UPDATED_AT) (direction DESC)))] number id state stateReason isReadByViewer (author login) title createdAt updatedAt closedAt locked (milestone id) body (assignees [(:edges t)] id) (comments [(:edges t)] id databaseId (author login) createdAt updatedAt body) (labels [(:edges t)] id)) (labels [(:edges t) (:singular label id)] id name color description) (milestones [(:edges t) (:singular milestone id)] id number title createdAt updatedAt dueOn closedAt description) (pullRequests [(:edges t) (:singular pullRequest number) (orderBy ((field UPDATED_AT) (direction DESC)))] number id state isReadByViewer (author login) title createdAt updatedAt closedAt mergedAt isDraft locked maintainerCanModify isCrossRepository (milestone id) body (baseRef name (repository nameWithOwner)) baseRefOid (headRef name (repository (owner login) nameWithOwner)) headRefOid (assignees [(:edges t)] id) (reviewRequests [(:edges t)] (requestedReviewer "... on User { id }\n")) (comments [(:edges t)] id databaseId (author login) createdAt updatedAt body) (labels [(:edges t)] id))))) (defconst ghub-fetch-repository-review-threads '(query (repository [(owner $owner String!) (name $name String!)] (pullRequests [(:edges t) (:singular pullRequest number) (orderBy ((field UPDATED_AT) (direction DESC)))] number baseRefOid headRefOid (reviewThreads [(:edges t)] id line originalLine diffSide (resolvedBy login) (comments [(:edges t)] id databaseId (author login) createdAt updatedAt body (replyTo databaseId) (originalCommit oid) path)))))) (cl-defun ghub-fetch-repository ( owner name callback &optional until &key username auth host forge headers paginate errorback sparse) "Asynchronously fetch forge data about the specified repository. Once all data has been collected, CALLBACK is called with the data as the only argument." (ghub-query (if sparse ghub-fetch-repository-sparse ghub-fetch-repository) `((owner . ,owner) (name . ,name)) :until until :narrow '(repository) :username username :auth auth :host host :forge forge :headers headers :paginate paginate :callback callback :errorback errorback)) (cl-defun ghub-fetch-discussion ( owner name number callback &optional until &key username auth host forge headers errorback) "Asynchronously fetch forge data about the specified discussion. Once all data has been collected, CALLBACK is called with the data as the only argument." (ghub-query (ghub--graphql-prepare-query ghub-fetch-repository `(repository discussions (discussion . ,number))) `((owner . ,owner) (name . ,name)) :until until :narrow '(repository discussion) :username username :auth auth :host host :forge forge :headers headers :callback callback :errorback errorback)) (cl-defun ghub-fetch-issue ( owner name number callback &optional until &key username auth host forge headers paginate errorback) "Asynchronously fetch forge data about the specified issue. Once all data has been collected, CALLBACK is called with the data as the only argument." (ghub-query (ghub--graphql-narrow-query ghub-fetch-repository `(repository issues (issue . ,number))) `((owner . ,owner) (name . ,name)) :until until :narrow '(repository issue) :username username :auth auth :host host :forge forge :headers headers :paginate paginate :callback callback :errorback errorback)) (cl-defun ghub-fetch-pullreq ( owner name number callback &optional until &key username auth host forge headers paginate errorback) "Asynchronously fetch forge data about the specified pull-request. Once all data has been collected, CALLBACK is called with the data as the only argument." (ghub-query (ghub--graphql-narrow-query ghub-fetch-repository `(repository pullRequests (pullRequest . ,number))) `((owner . ,owner) (name . ,name)) :until until :narrow '(repository pullRequest) :username username :auth auth :host host :forge forge :headers headers :paginate paginate :callback callback :errorback errorback)) (cl-defun ghub-fetch-review-threads ( owner name number callback &optional until &key username auth host forge headers paginate errorback) "Asynchronously fetch forge data about the review threads from a pull-request. Once all data has been collected, CALLBACK is called with the data as the only argument." (ghub-query (ghub--graphql-narrow-query ghub-fetch-repository-review-threads `(repository pullRequests (pullRequest . ,number))) `((owner . ,owner) (name . ,name)) :until until :narrow '(repository pullRequest) :username username :auth auth :host host :forge forge :headers headers :paginate paginate :callback callback :errorback errorback)) ;;; _ (provide 'ghub-legacy) ;;; ghub-legacy.el ends here ghub-5.0.1/lisp/ghub.el000066400000000000000000001012731507100422500146600ustar00rootroot00000000000000;;; ghub.el --- Client libraries for Git forge APIs -*- lexical-binding:t -*- ;; Copyright (C) 2016-2025 Jonas Bernoulli ;; Author: Jonas Bernoulli ;; Homepage: https://github.com/magit/ghub ;; Keywords: tools ;; Package-Version: 5.0.1 ;; Package-Requires: ( ;; (emacs "29.1") ;; (compat "30.1") ;; (llama "1.0") ;; (treepy "0.1.2")) ;; SPDX-License-Identifier: GPL-3.0-or-later ;; This file is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published ;; by the Free Software Foundation, either version 3 of the License, ;; or (at your option) any later version. ;; ;; This file is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; ;; You should have received a copy of the GNU General Public License ;; along with this file. If not, see . ;;; Commentary: ;; Ghub provides basic support for using the APIs of various Git forges ;; from Emacs packages. Originally it only supported the Github REST ;; API, but now it also supports the Github GraphQL API as well as the ;; REST APIs of Gitlab, Gitea, Gogs and Bitbucket. ;; Ghub abstracts access to API resources using only a handful of basic ;; functions such as `ghub-get'. These are convenience wrappers around ;; `ghub-request'. ;; When accessing Github, then Ghub handles the creation and storage of ;; access tokens using a setup wizard to make it easier for users to get ;; started. The tokens for other forges have to be created manually. ;; Ghub is intentionally limited to only provide these two essential ;; features — basic request functions and guided setup — to avoid being ;; too opinionated, which would hinder wide adoption. It is assumed that ;; wide adoption would make life easier for users and maintainers alike, ;; because then all packages that talk to forge APIs could be configured ;; the same way. ;; Please consult the manual (info "ghub") for more information. ;;; Code: (require 'auth-source) (require 'cl-lib) (require 'compat) (require 'gnutls) (require 'let-alist) (require 'llama) (require 'url) (require 'url-auth) (require 'url-http) (eval-when-compile (require 'subr-x)) (defvar url-callback-arguments) (defvar url-http-end-of-headers) (defvar url-http-extra-headers) (defvar url-http-response-status) ;;; Settings (defvar ghub-default-host-alist '((github . "api.github.com") (gitlab . "gitlab.com/api/v4") (gitea . "localhost:3000/api/v1") (gogs . "localhost:3000/api/v1") (bitbucket . "api.bitbucket.org/2.0")) "Alist of default hosts used when the respective `FORGE.host' is not set.") (defvar ghub-github-token-scopes '(repo) "The Github API scopes that your private tools need. You have to manually create or update the token at https://github.com/settings/tokens. This variable only serves as documentation.") (defvar ghub-insecure-hosts nil "List of hosts that use http instead of https.") (defvar ghub-debug nil "Record additional debug information.") ;;; Request ;;;; Object (cl-defstruct (ghub--req (:constructor ghub--make-req) (:copier nil)) (url nil :read-only nil) (forge nil :read-only t) (silent nil :read-only t) (method nil :read-only t) (headers nil :read-only t) (handler nil :read-only t) (unpaginate nil :read-only nil) (noerror nil :read-only t) (reader nil :read-only t) (buffer nil :read-only t) (synchronous nil :read-only t) (callback nil :read-only t) (errorback nil :read-only t) (value nil :read-only nil) (extra nil :read-only nil)) (defalias 'ghub-req-extra #'ghub--req-extra) ;;;; API (define-error 'ghub-error "Ghub/Url Error" 'error) (define-error 'ghub-http-error "HTTP Error" 'ghub-error) (defvar ghub-response-headers nil "The headers returned in response to the last request. `ghub-request' returns the response body and stores the response headers in this variable.") (cl-defun ghub-head (resource &optional params &key query payload headers silent unpaginate noerror reader username auth host callback errorback extra) "Make a `HEAD' request for RESOURCE, with optional query PARAMS. Like calling `ghub-request' (which see) with \"HEAD\" as METHOD." (ghub-request "HEAD" resource params :query query :payload payload :headers headers :silent silent :unpaginate unpaginate :noerror noerror :reader reader :username username :auth auth :host host :callback callback :errorback errorback :extra extra)) (cl-defun ghub-get (resource &optional params &key query payload headers silent unpaginate noerror reader username auth host forge callback errorback extra) "Make a `GET' request for RESOURCE, with optional query PARAMS. Like calling `ghub-request' (which see) with \"GET\" as METHOD." (ghub-request "GET" resource params :query query :payload payload :headers headers :silent silent :unpaginate unpaginate :noerror noerror :reader reader :username username :auth auth :host host :forge forge :callback callback :errorback errorback :extra extra)) (cl-defun ghub-put (resource &optional params &key query payload headers silent unpaginate noerror reader username auth host forge callback errorback extra) "Make a `PUT' request for RESOURCE, with optional payload PARAMS. Like calling `ghub-request' (which see) with \"PUT\" as METHOD." (ghub-request "PUT" resource params :query query :payload payload :headers headers :silent silent :unpaginate unpaginate :noerror noerror :reader reader :username username :auth auth :host host :forge forge :callback callback :errorback errorback :extra extra)) (cl-defun ghub-post (resource &optional params &key query payload headers silent unpaginate noerror reader username auth host forge callback errorback extra) "Make a `POST' request for RESOURCE, with optional payload PARAMS. Like calling `ghub-request' (which see) with \"POST\" as METHOD." (ghub-request "POST" resource params :query query :payload payload :headers headers :silent silent :unpaginate unpaginate :noerror noerror :reader reader :username username :auth auth :host host :forge forge :callback callback :errorback errorback :extra extra)) (cl-defun ghub-patch (resource &optional params &key query payload headers silent unpaginate noerror reader username auth host forge callback errorback extra) "Make a `PATCH' request for RESOURCE, with optional payload PARAMS. Like calling `ghub-request' (which see) with \"PATCH\" as METHOD." (ghub-request "PATCH" resource params :query query :payload payload :headers headers :silent silent :unpaginate unpaginate :noerror noerror :reader reader :username username :auth auth :host host :forge forge :callback callback :errorback errorback :extra extra)) (cl-defun ghub-delete (resource &optional params &key query payload headers silent unpaginate noerror reader username auth host forge callback errorback extra) "Make a `DELETE' request for RESOURCE, with optional payload PARAMS. Like calling `ghub-request' (which see) with \"DELETE\" as METHOD." (ghub-request "DELETE" resource params :query query :payload payload :headers headers :silent silent :unpaginate unpaginate :noerror noerror :reader reader :username username :auth auth :host host :forge forge :callback callback :errorback errorback :extra extra)) (cl-defun ghub-request ( method resource &optional params &key query payload headers silent unpaginate noerror reader username auth host forge callback errorback value extra) "Make a request for RESOURCE and return the response body. Also place the response headers in `ghub-response-headers'. METHOD is the HTTP method, given as a string. RESOURCE is the resource to access, given as a string beginning with a slash. PARAMS, QUERY, PAYLOAD and HEADERS are alists used to specify data. The Github API documentation is vague on how data has to be transmitted and for a particular resource usually just talks about \"parameters\". Generally speaking when the METHOD is \"HEAD\" or \"GET\", then they have to be transmitted as a query, otherwise as a payload. Use PARAMS to automatically transmit like QUERY or PAYLOAD would depending on METHOD. Use QUERY to explicitly transmit data as a query. Use PAYLOAD to explicitly transmit data as a payload. Instead of an alist, PAYLOAD may also be a string, in which case it gets encoded as UTF-8 but is otherwise transmitted as-is. Use HEADERS for those rare resources that require that the data is transmitted as headers instead of as a query or payload. When that is the case, then the API documentation usually mentions it explicitly. If SILENT is non-nil, then don't message progress reports and the like. If UNPAGINATE is t, then make as many requests as necessary to get all values. If UNPAGINATE is a natural number, then get at most that many pages. For any other non-nil value raise an error. If NOERROR is non-nil, then do not raise an error if the request fails and return nil instead. If NOERROR is `return', then return the error payload instead of nil. If READER is non-nil, then it is used to read and return from the response buffer. The default is `ghub--read-json-payload'. For the very few resources that do not return JSON, you might want to use `ghub--decode-payload'. If USERNAME is non-nil, then make a request on behalf of that user. It is better to specify the user using the Git variable `github.user' for \"api.github.com\", or `github.HOST.user' if connecting to a Github Enterprise instance. Each package that uses `ghub' should use its own token. If AUTH is nil, then the generic `ghub' token is used instead. This is only acceptable for personal utilities. A packages that is distributed to other users should always use this argument to identify itself, using a symbol matching its name. Package authors who find this inconvenient should write a wrapper around this function and possibly for the method-specific functions as well. Some symbols have a special meaning. `none' means to make an unauthorized request. `basic' means to make a password based request. If the value is a string, then it is assumed to be a valid token. `basic' and an explicit token string are only intended for internal and debugging uses. If HOST is non-nil, then connect to that Github instance. This defaults to \"api.github.com\". When a repository is connected to a Github Enterprise instance, then it is better to specify that using the Git variable `github.host' instead of using this argument. If optional FORGE is nil, then it is assumed that HOST is a Github host. When connecting to another forge type, then FORGE must be one of `gitlab', `gitea', `gogs' or `bitbucket'. If CALLBACK and/or ERRORBACK is non-nil, then make one or more asynchronous requests and call CALLBACK or ERRORBACK when finished. If no error occurred, then call CALLBACK, unless that is nil. If an error occurred, then call ERRORBACK, or if that is nil, then CALLBACK. ERRORBACK can also be t, in which case an error is signaled instead. NOERROR is ignored for all asynchronous requests. Both callbacks are called with four arguments. 1. For CALLBACK, the combined value of the retrieved pages. For ERRORBACK, the error that occurred when retrieving the last page. 2. The headers of the last page as an alist. 3. Status information provided by `url-retrieve'. Its `:error' property holds the same information as ERRORBACK's first argument. 4. A `ghub--req' struct, which can be passed to `ghub-continue' (which see) to retrieve the next page, if any." (declare (indent defun)) (cl-assert (or (booleanp unpaginate) (natnump unpaginate))) (unless (string-prefix-p "/" resource) (setq resource (concat "/" resource))) (unless host (setq host (ghub--host forge))) (unless (or username (stringp auth) (eq auth 'none)) (setq username (ghub--username host forge))) (cond ((not params)) ((member method '("GET" "HEAD")) (when query (error "PARAMS and QUERY are mutually exclusive for METHOD %S" method)) (setq query params)) (t (when payload (error "PARAMS and PAYLOAD are mutually exclusive for METHOD %S" method)) (setq payload params))) (when (or callback errorback) (setq noerror t)) (ghub--retrieve (ghub--encode-payload payload) (ghub--make-req :url (ghub--encode-url host resource query) :forge forge :silent silent :method (encode-coding-string method 'utf-8) ;#35 :headers (ghub--headers headers host auth username forge) :handler #'ghub--handle-response :unpaginate unpaginate :noerror noerror :reader reader :buffer (current-buffer) :synchronous (not (or callback errorback)) :callback callback :errorback errorback :value value :extra extra))) (defun ghub-continue (req) "If there is a next page, then retrieve that. This function is only intended to be called from callbacks. If there is a next page, then retrieve that and return the buffer that the result will be loaded into, or t if the process has already completed. If there is no next page, then return nil. Callbacks are called with four arguments (see `ghub-request'). The forth argument is a `ghub--req' struct, intended to be passed to this function. A callback may use the struct's `extra' slot to pass additional information to the callback that will be called after the next request has finished. Use the function `ghub-req-extra' to get and set the value of this slot." (and (assq 'next (ghub-response-link-relations req)) (or (ghub--retrieve nil req) t))) (cl-defun ghub-wait (resource &optional duration &key username auth host forge) "Busy-wait up to DURATION seconds for RESOURCE to become available. DURATION specifies how many seconds to wait at most. It defaults to 64 seconds. The first attempt is made immediately, the second after two seconds, and each subsequent attempt is made after waiting as long again as we already waited between all preceding attempts combined. See `ghub-request' for information about the other arguments." (unless duration (setq duration 64)) (with-local-quit (let ((total 0)) (while (not (ghub-request "GET" resource nil :noerror t :username username :auth auth :host host :forge forge)) (message "Waited (%3ss of %ss) for %s..." total duration resource) (if (= total duration) (error "%s is taking too long to create %s" (if forge (capitalize (symbol-name forge)) "Github") resource) (if (> total 0) (let ((wait (min total (- duration total)))) (sit-for wait) (cl-incf total wait)) (sit-for (setq total 2)))))))) (defun ghub-response-link-relations (req &optional headers payload) "Return an alist of link relations in HEADERS. If optional HEADERS is nil, then return those that were previously stored in the variable `ghub-response-headers'. When accessing a Bitbucket instance then the link relations are in PAYLOAD instead of HEADERS, making their API merely RESTish and forcing this function to append those relations to the value of `ghub-response-headers', for later use when this function is called with nil for PAYLOAD." (if (eq (ghub--req-forge req) 'bitbucket) (if payload (let* ((page (seq-keep (##assq % payload) '(size page pagelen next previous))) (headers (cons (cons 'link-alist page) headers))) (if (and req (or (ghub--req-callback req) (ghub--req-errorback req))) (setq-local ghub-response-headers headers) (setq-default ghub-response-headers headers)) page) (cdr (assq 'link-alist ghub-response-headers))) (and-let* ((headers (or headers ghub-response-headers)) (rels (cdr (or (assoc "Link" headers) (assoc "link" headers))))) (mapcar (lambda (elt) (pcase-let ((`(,url ,rel) (split-string elt "; "))) (cons (intern (substring rel 5 -1)) (substring url 1 -1)))) (split-string rels ", ?"))))) (cl-defun ghub-repository-id (owner name &key username auth host forge noerror) "Return the id of the specified repository. Signal an error if the id cannot be determined." (or (pcase forge ((or 'nil 'github) (let-alist (ghub-graphql '(query (repository [(owner $owner String!) (name $name String!)] id)) `((owner . ,owner) (name . ,name)) :username username :auth auth :host host) .data.repository.id)) ('gitlab (number-to-string (alist-get 'id (ghub-get (format "/projects/%s%%2F%s" (string-replace "/" "%2F" owner) name) nil :forge 'gitlab :username username :auth auth :host host)))) ((or 'forgejo 'gitea 'gogs) (number-to-string (alist-get 'id (ghub-get (format "/repos/%s/%s" owner name) nil :forge forge :username username :auth auth :host host)))) ('bitbucket (substring (alist-get 'uuid (ghub-get (format "/repositories/%s/%s" owner name) nil :forge 'bitbucket :username username :auth auth :host host)) 1 -1)) (_ (error "ghub-repository-id: Forge type `%s' is unknown" forge))) (and (not noerror) (error "Repository %S does not exist on %S.\n%s%S?" (concat owner "/" name) (or host (ghub--host forge)) "Maybe it was renamed and you have to update " "remote..url")))) ;;;; Internal (cl-defun ghub--retrieve (payload req) (pcase-let* (((cl-struct ghub--req headers method url handler silent synchronous) req) (url-request-extra-headers (if (functionp headers) (funcall headers) headers)) (url-request-method method) (url-request-data payload) (url-show-status nil)) (if synchronous (if-let ((buf (url-retrieve-synchronously url silent))) (with-current-buffer buf (funcall handler (car url-callback-arguments) req)) (error "ghub--retrieve: No buffer returned")) (url-retrieve url handler (list req) silent)))) (defun ghub--handle-response (status req) (let ((buf (current-buffer))) (unwind-protect (progn (set-buffer-multibyte t) (let* ((unpaginate (ghub--req-unpaginate req)) (headers (ghub--handle-response-headers status req)) (payload (ghub--handle-response-payload req)) (payload (ghub--handle-response-error status payload req)) (value (ghub--handle-response-value payload req)) (prev (ghub--req-url req)) (next (cdr (assq 'next (ghub-response-link-relations req headers payload))))) (when (numberp unpaginate) (cl-decf unpaginate)) (setf (ghub--req-url req) (url-generic-parse-url next)) (setf (ghub--req-unpaginate req) unpaginate) (or (and next unpaginate (or (eq unpaginate t) (> unpaginate 0)) (ghub-continue req)) (let ((req-buf (ghub--req-buffer req)) (callback (ghub--req-callback req)) (errorback (ghub--req-errorback req)) (err (plist-get status :error))) (cond ((and err errorback) (setf (ghub--req-url req) prev) (funcall (if (eq errorback t) 'ghub--errorback errorback) err headers status req)) (callback (save-current-buffer (when (buffer-live-p req-buf) (set-buffer req-buf)) (funcall callback value headers status req))) (t value)))))) (when (and (buffer-live-p buf) (not (buffer-local-value 'ghub-debug buf))) (kill-buffer buf))))) (defun ghub--handle-response-headers (_status req) (let (headers) (when (memq url-http-end-of-headers '(nil 0)) (unless url-debug (setq url-debug t)) (error "BUG: Missing headers in response buffer %s" (current-buffer))) (goto-char (point-min)) (forward-line 1) (while (re-search-forward "^\\([^:]*\\): \\(.+\\)" url-http-end-of-headers t) (push (cons (match-string 1) (match-string 2)) headers)) (setq headers (nreverse headers)) (goto-char (1+ url-http-end-of-headers)) (if (and req (or (ghub--req-callback req) (ghub--req-errorback req))) (setq-local ghub-response-headers headers) (setq-default ghub-response-headers headers)) headers)) (defun ghub--handle-response-error (status payload req) (if-let ((err (plist-get status :error))) (if-let ((noerror (ghub--req-noerror req))) (if (eq noerror 'return) payload (setcdr (last err) (list payload)) nil) (ghub--signal-error err payload req)) payload)) (defun ghub--signal-error (err &optional payload req) (pcase-let ((`(,symb . ,data) err)) (if (eq symb 'error) (if (eq (car-safe data) 'http) (signal 'ghub-http-error (let ((code (car (cdr-safe data)))) (list code (nth 2 (assq code url-http-codes)) (and req (url-recreate-url (ghub--req-url req))) payload))) (signal 'ghub-error data)) (signal symb data)))) (defun ghub--errorback (err _headers _status req) (ghub--signal-error err (nth 3 err) req)) (defun ghub--handle-response-value (payload req) (setf (ghub--req-value req) (nconc (ghub--req-value req) (if-let ((nested (and (eq (ghub--req-forge req) 'bitbucket) (assq 'values payload)))) (cdr nested) payload)))) (defun ghub--handle-response-payload (req) (funcall (or (ghub--req-reader req) 'ghub--read-json-payload) url-http-response-status)) (defun ghub--read-json-payload (_status &optional json-type-args) (and-let* ((payload (ghub--decode-payload))) (ghub--assert-json-available) (condition-case nil (apply #'json-parse-string payload (or json-type-args '( :object-type alist :array-type list :null-object nil :false-object nil))) (json-parse-error (when ghub-debug (pop-to-buffer (current-buffer))) (setq-local ghub-debug t) `((message . ,(if (looking-at "") (if (re-search-forward "

\\(?:\\)?\\([^<]+\\)" nil t) (match-string 1) "error description missing") (string-trim (buffer-substring (point) (point-max))))) (documentation_url . "https://github.com/magit/ghub/wiki/Github-Errors")))))) (defun ghub--decode-payload (&optional _status) (and (not (eobp)) (decode-coding-string (buffer-substring-no-properties (point) (point-max)) 'utf-8))) (defun ghub--encode-payload (payload) (cl-typecase payload (null nil) (string (encode-coding-string payload 'utf-8)) (t (ghub--assert-json-available) (encode-coding-string (json-serialize payload :null-object :null :false-object nil) 'utf-8)))) (defun ghub--encode-url (host resource &optional query) (url-generic-parse-url (concat (if (member host ghub-insecure-hosts) "http://" "https://") ;; Needed for some Github Enterprise instances. (cond ((and (equal resource "/graphql") (string-suffix-p "/v3" host)) (substring host 0 -3)) ;; Needed for all Gitlab instances. ((and (equal resource "/api/graphql") (string-suffix-p "/api/v4" host)) (substring host 0 -7)) (host)) resource (and query (concat "?" (ghub--url-encode-params query)))))) (defun ghub--url-encode-params (params) (mapconcat (lambda (param) (pcase-let ((`(,key . ,val) param)) (concat (url-hexify-string (symbol-name key)) "=" (cl-typecase val (integer (number-to-string val)) (boolean (if val "true" "false")) (t (url-hexify-string val)))))) params "&")) (defun ghub--assert-json-available () (unless (and (fboundp 'json-available-p) (json-available-p)) (error "Ghub requires Emacs 29 --with-json or Emacs >= 30"))) ;;; Authentication ;;;; API ;;;###autoload (defun ghub-clear-caches () "Clear all caches that might negatively affect Ghub. If a library that is used by Ghub caches incorrect information such as a mistyped password, then that can prevent Ghub from asking the user for the correct information again. Set `url-http-real-basic-auth-storage' to nil and call `auth-source-forget+'." (interactive) (setq url-http-real-basic-auth-storage nil) (auth-source-forget+)) ;;;; Internal (defun ghub--headers (headers host auth username forge) (push (cons "Content-Type" "application/json") headers) (if (eq auth 'none) headers (unless (or username (stringp auth)) (setq username (ghub--username host forge))) (lambda () (if (eq auth 'basic) (cons (cons "Authorization" (ghub--basic-auth host username)) headers) (cons (ghub--auth host auth username forge) headers))))) (cl-defgeneric ghub--auth (host auth &optional username forge) (unless username (setq username (ghub--username host forge))) (if (eq auth 'basic) (pcase-exhaustive forge ((or 'nil 'forgejo 'gitea 'gogs 'bitbucket) (cons "Authorization" (ghub--basic-auth host username))) ((or 'github 'gitlab) (error "%s does not support basic authentication" (capitalize (symbol-name forge))))) (cons (pcase-exhaustive forge ((or 'nil 'forgejo 'github 'gitea 'gogs 'bitbucket) "Authorization") ('gitlab "Private-Token")) (if (eq forge 'bitbucket) ;; For some undocumented reason Bitbucket supports ;; values of the form "token " only for GET ;; requests. For PUT requests we have to use basic ;; authentication. Note that the secret is a token ;; (aka "app password"), not the actual password. ;; The documentation fails to mention this little ;; detail. See #97. (concat "Basic " (base64-encode-string (concat username ":" (ghub--token host username auth nil forge)) t)) (concat (and (not (eq forge 'gitlab)) "token ") (encode-coding-string (cl-typecase auth (string auth) (null (ghub--token host username 'ghub nil forge)) (symbol (ghub--token host username auth nil forge)) (t (signal 'wrong-type-argument `((or stringp symbolp) ,auth)))) 'utf-8)))))) (defun ghub--basic-auth (host username) (let ((url (url-generic-parse-url (if (member host ghub-insecure-hosts) "http://" "https://")))) (setf (url-user url) username) (url-basic-auth url t))) (defun ghub--token (host username package &optional nocreate forge) (let* ((user (ghub--ident username package)) (token (or (ghub--auth-source-get :secret :host host :user user) (and (string-match "\\`\\([^/]+\\)" host) (ghub--auth-source-get :secret :host (match-string 1 host) :user user))))) (unless (or token nocreate) (error "\ Required %s token (%S for %s%S) does not exist. See https://magit.vc/manual/ghub/Getting-Started.html or (info \"(ghub)Getting Started\") for instructions." (capitalize (symbol-name (or forge 'github))) user (if (string-match "\\`\\([^/]+\\)" host) (format "either %S or " (match-string 1 host)) "") host)) (if (functionp token) (funcall token) token))) (cl-defmethod ghub--host (&optional forge) (let ((forge (or forge 'github))) (or (ghub--git-get (format "%s.host" forge)) (alist-get forge ghub-default-host-alist)))) (cl-defmethod ghub--username (host &optional forge) (let* ((forge (or forge 'github)) (host (or host (ghub--host forge))) (var (format "%s.%s.user" forge host))) (or (ghub--git-get var) (if-let ((_(equal host (alist-get forge ghub-default-host-alist))) (default-var (format "%s.user" forge))) (or (ghub--git-get default-var) (user-error "%s; `%s' and `%s' are both unset" "Cannot determine username" var default-var)) (user-error "Cannot determine username; `%s' is unset" var))))) (defun ghub--ident (username package) (format "%s^%s" username package)) (defun ghub--auth-source-get (keys &rest spec) (declare (indent 1)) (if-let ((plist (car (apply #'auth-source-search spec)))) (if (keywordp keys) (plist-get plist keys) (mapcar (##plist-get plist %) keys)) ;; Auth-Source caches the information that there is no value, but in ;; our case that is a situation that needs fixing, so we want to keep ;; trying, by invalidating that information. (auth-source-forget spec) nil)) (define-advice auth-source-netrc-parse (:around (fn &rest args) handle-symlink) "Follow symlinks for FILE before comparing modification times." (let ((file (plist-get args :file))) (when (and (stringp file) (file-exists-p file)) (setq args (plist-put args :file (file-chase-links file))))) (apply fn args)) (defun ghub--git-get (var) (catch 'non-zero (car (process-lines-handling-status "git" (##unless (zerop %) (throw 'non-zero nil)) ;; Beginning with Git v2.46 we could use "get". "config" "--get" var)))) ;;; _ (provide 'ghub) (require 'ghub-graphql) (require 'ghub-legacy) ;;; ghub.el ends here ghub-5.0.1/lisp/gsexp.el000066400000000000000000000064571507100422500150710ustar00rootroot00000000000000;;; gsexp.el --- GraphQl as S-expressions -*- lexical-binding:t -*- ;; Copyright (C) 2016-2025 Jonas Bernoulli ;; Author: Jonas Bernoulli ;; Homepage: https://github.com/magit/ghub ;; Keywords: tools ;; SPDX-License-Identifier: GPL-3.0-or-later ;; This file is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published ;; by the Free Software Foundation, either version 3 of the License, ;; or (at your option) any later version. ;; ;; This file is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; ;; You should have received a copy of the GNU General Public License ;; along with this file. If not, see . ;;; Commentary: ;; This library encodes S-expressions as GraphQl documents. Currently ;; it is rather incomplete and only intended for use by `ghub-graphql' ;; but I might fill the gaps and add documentation eventually. I am ;; not in a hurry though. ;;; Code: (require 'cl-lib) (defvar gsexp-one-variable-per-line nil) (defun gsexp-encode (document) (gsexp--pp (gsexp--encode-field document))) (defun gsexp--encode-field (field) (cond ((stringp field) field) ((symbolp field) (symbol-name field)) ((listp (car field)) (concat (format "%s: " (caar field)) (gsexp--encode-field (cons (car (cdar field)) (cdr field))))) ((concat (pcase (pop field) (`[] "") ((and (pred symbolp) op) (symbol-name op)) (`[,op] (symbol-name op)) (`[,op ,name] (format "%s %s" op name))) (and (vectorp (car field)) (format " (%s%s)" (if gsexp-one-variable-per-line "\n" "") (mapconcat #'gsexp--encode-argument (append (pop field) nil) (if gsexp-one-variable-per-line ",\n" ",")))) (and field (format " {\n%s\n}" (mapconcat #'gsexp--encode-field field "\n"))))))) (cl-defun gsexp--encode-argument ((argument value)) (format "%s: %s" argument (gsexp--encode-value value))) (defun gsexp--encode-value (value) (cond ((numberp value) (number-to-string value)) ((symbolp value) ; including variables, enums, booleans and null (symbol-name value)) ((stringp value) (prin1-to-string value)) ((vectorp value) (format "(%s)" (mapconcat #'gsexp--encode-value value ""))) ((listp value) (format "{%s}" (mapconcat (pcase-lambda (`(,name ,value)) (format "%s: %s" name (gsexp--encode-value value))) value ", "))) ((error "Invalid field value: %S" value)))) (defun gsexp--pp (string) (with-temp-buffer (save-excursion (insert string)) (while (< (point) (point-max)) (unless (and (bolp) (eolp)) (save-excursion (let ((level (car (syntax-ppss (line-beginning-position))))) (when (looking-at "\\s-*\\s)") (cl-decf level)) (indent-line-to (* 2 level))))) (forward-line 1)) (buffer-string))) ;;; _ (provide 'gsexp) ;;; gsexp.el ends here