Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/karimaziev/github-code-search

Search and browse code on github for a given language and filename.
https://github.com/karimaziev/github-code-search

Last synced: 4 days ago
JSON representation

Search and browse code on github for a given language and filename.

Awesome Lists containing this project

README 

        
#+OPTIONS: ^:nil tags:nil



* About



This Emacs package provides an interface for executing code searches on GitHub using Emacs' transient interface.



*Features*:

- Search GitHub repositories and gists by code, language, filename, user, or organization.

- Open files and jump to code results in Emacs.

- Highlight relevant search terms and toggle the completeness of matches.

- Transient menu to quickly configure different GitHub queries.

- Clone and explore repositories from within Emacs (requires [[https://github.com/KarimAziev/gh-repo][gh-repo]]).



[[./github-code-search.gif]]



* Table of Contents                                       :TOC_2_gh:QUOTE:

#+BEGIN_QUOTE

- [[#about][About]]

- [[#requirements][Requirements]]

- [[#installation][Installation]]

  - [[#with-use-package-and-straightel][With use-package and straight.el]]

  - [[#manual-installation][Manual installation]]

- [[#setup][Setup]]

- [[#usage][Usage]]

#+END_QUOTE



* Requirements



| Name               | Version |

|--------------------+---------|

| Emacs              |    28.1 |

| ~transient~        |   0.4.1 |

| ~ghub~             |   3.6.0 |

| [[https://github.com/KarimAziev/gh-repo][gh-repo]] (optional) |   1.1.0 |



* Installation



** With use-package and straight.el

#+begin_src elisp :eval no

(use-package github-code-search

  :straight (github-code-search

             :repo "KarimAziev/github-code-search"

             :type git

             :host github))



;; optionally, for viewing repository tree, readme and files

(use-package gh-repo

  :straight (gh-repo

             :repo "KarimAziev/gh-repo"

             :type git

             :host github))

#+end_src



** Manual installation



Download the source code and put it wherever you like, e.g. into =~/.emacs.d/github-code-search/=



#+begin_src shell :eval no

git clone https://github.com/KarimAziev/github-code-search.git ~/.emacs.d/github-code-search/

#+end_src



Add the downloaded directory to the load path:



#+begin_src elisp :eval no

(add-to-list 'load-path "~/.emacs.d/github-code-search/")

(require 'github-code-search)

#+end_src



* Setup



=github-code-search= manages authentication through the customizable variable =github-code-search-ghub-auth-info=, which should be either a cons of (USERNAME . TOKEN) or a function that returns it. The TOKEN can be either a string containing the OAuth token, or a symbol indicating where to fetch the OAuth token.



*** Setting Up token



Firsly, you need to ensure that you have [[https://github.com/settings/tokens][a GitHub API token]].



1. Log in to your GitHub account and navigate to settings.

2. Select the Developer settings option on the bottom of the sidebar.

3. Here you'll see a Personal access tokens section, click on it.

4. Click on "Generate new token", give your token a descriptive name.

5. Click on Generate token at the bottom of the page. Be sure to copy your new personal access token now as you cannot see it again.



After getting your token, you can supply it to =github-code-search= in one of two ways.



*** Secure Way: Using auth-sources



Emacs =auth-sources= provide a secure way to store your GitHub username and OAuth token.



To employ this method, set =github-code-search-token= to the symbol =github-code-search=:



#+begin_src elisp

(setq github-code-search-ghub-auth-info '("YOUR-GITHUB-USERNAME" . github-code-search))

#+end_src



Next, add an entry to your =auth-sources=:



#+begin_example

machine api.github.com login YOUR-GITHUB-USERNAME^github-code-search password YOUR-GITHUB-TOKEN

#+end_example



You can add this entry to your =~/.authinfo.gpg= file (recommended for secure, encrypted storage) or =~/.authinfo= (see variable =auth-sources=).



You can read more in [[https://magit.vc/manual/forge/Token-Creation.html#Token-Creation][ghub]] manual, as =github-code-search= relies on the provided API.



*** Insecure way



While not recommended due to security issues, you can set =github-code-search-token= and =github-code-search-user= in your Emacs config file:



#+begin_src elisp

(setq github-code-search-ghub-auth-info '("your-github-username" . "YOUR-GITHUB-OAUTH-TOKEN"))

#+end_src



If you logged in =gh= cli and want to reuse the user and oauth token you can use:



#+begin_src elisp

(setq github-code-search-ghub-auth-info #'github-code-search-auth-from-gh-config)

#+end_src



*Note*: In this method, your OAuth token will be stored as plain text in your emacs config file, which is insecure. Ensure your config file permissions are appropriately set to prevent unauthorized access.



* Usage



To run the GitHub code search in Emacs, use the command =M-x github-code-search=. This will open a menu for the GitHub code search, where you can enter a specific code query.



[[./github-code-search.png]]



After entering the search term, you can either press =RET= to load and display the results in Emacs, or press =C-c C-o= to open the results in a browser.



In search buffers, you can also run =M-x github-code-search-file-result-menu= (by default, it is bound to =?= and =C-h ?=) to open a menu with all available actions.



[[./github-code-search-result-menu.png]]