{"id":13862820,"url":"https://github.com/iliabv/emacs-bpr","last_synced_at":"2025-07-14T13:32:40.146Z","repository":{"id":148931617,"uuid":"45339221","full_name":"iliabv/emacs-bpr","owner":"iliabv","description":null,"archived":false,"fork":false,"pushed_at":"2018-12-08T23:52:29.000Z","size":1078,"stargazers_count":63,"open_issues_count":1,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-05-15T13:18:11.783Z","etag":null,"topics":["background-jobs","emacs","emacs-lisp","processes"],"latest_commit_sha":null,"homepage":null,"language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iliabv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-11-01T12:19:02.000Z","updated_at":"2024-03-08T23:55:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"34a04d93-a58d-444d-87fe-8271005430bb","html_url":"https://github.com/iliabv/emacs-bpr","commit_stats":null,"previous_names":["iliabv/emacs-bpr"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iliabv%2Femacs-bpr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iliabv%2Femacs-bpr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iliabv%2Femacs-bpr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iliabv%2Femacs-bpr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iliabv","download_url":"https://codeload.github.com/iliabv/emacs-bpr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225980898,"owners_count":17554919,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["background-jobs","emacs","emacs-lisp","processes"],"created_at":"2024-08-05T06:01:53.342Z","updated_at":"2024-11-22T23:30:29.012Z","avatar_url":"https://github.com/iliabv.png","language":"Emacs Lisp","funding_links":[],"categories":["Emacs Lisp"],"sub_categories":[],"readme":"[![MELPA](http://melpa.org/packages/bpr-badge.svg)](http://melpa.org/#/bpr) [![Build Status](https://travis-ci.org/ilya-babanov/emacs-bpr.svg)](https://travis-ci.org/ilya-babanov/emacs-bpr) \n## Emacs-BPR (Background Process Runner)\nThis package provides logic for async process execution.\n\nIt's similar to `async-shell-command`, but:\n- `bpr` spawns processes asynchronously without displaying output buffers.\n- `bpr` shows progress messages for running processes in echo area.\n- `bpr` can display buffer with process output in case of errors.\n- `bpr` can use `projectile` for assigning process directory.\n- `bpr` can format process output (understands ansi escape codes).\n- you can add handlers for `completion/success/error` events\n- you can set different options for different processes.\n\n`bpr` is very handy for running tests/builds, but you can run any processes with it. \n\n## Example\nGiven this configuration:\n```elisp\n(require 'bpr)\n\n;; Set global config for bpr.\n;; Variables below are applied to all processes.\n(setq bpr-colorize-output t)\n(setq bpr-close-after-success t)\n\n;; define function for running desired process\n(defun run-tests ()\n  \"Spawns 'grunt test' process\"\n  (interactive)\n  ;; Set dynamic config for process.\n  ;; Variables below are applied only to particular process\n  (let* ((bpr-scroll-direction -1))\n    (bpr-spawn \"grunt test --color\")))\n\n;; set key-binding\n(define-key global-map \"\\C-ct\" 'run-tests)\n```\nYou get this behavior for success:\n![grunt test success](./img/success-run.gif)\nAnd this for error:\n![grunt test error](./img/error-run.gif)\n\nWhat's happening:\n- User enters predefined key-binding, which invokes function `run-tests`.\n- `bpr-spawn` starts async process `grunt test --color` and writes progress messages in echo area.\n- If process ends successfully - success message is being shown.\n- If process ends with error - error message is being shown and window with output buffer is being opened.\n\n## Installation\n### MELPA\n`M-x package-install bpr`\n\n### Manually\n```elisp\n;; If you have cloned this repo into `~/some-path/emacs-bpr/`\n(add-to-list 'load-path \"~/some-path/emacs-bpr/\")\n(require 'bpr)\n```\n\n## Configuration\nIf you want to set options globally for all processes:\n```elisp\n(require 'bpr)\n\n;; use ansi-color-apply-on-region function on output buffer\n(setq bpr-colorize-output t)\n\n;; use comint-mode for processes output buffers instead of shell-mode\n(setq bpr-process-mode #'comint-mode)\n\n;; call `do-something` whenever bpr-spawn's process is compelted\n(setq bpr-on-completion #'do-something)\n```\n\nIf you want to set options to particular process, set them dynamically right before `bpr-spawn`:\n```elisp\n(let* (;; don't erase process output buffer before starting this process again.\n       (bpr-erase-process-buffer nil)\n       ;; don't show progress messages (only success/error messages will be displayed)\n       (bpr-show-progress nil)\n       ;; call `do-something` when process below is successfully completed\n       (bpr-on-success #'do-something))\n    (bpr-spawn \"ping -c 4 www.wikipedia.org\"))\n```\n\nDefault directory for processes is `default-directory` of current buffer, but with `projectile` installed, `bpr` would use `projectile-project-root` function. To disable projectile support, set `bpr-use-projectile` to nil. If you want to set custom logic for project root detection, just reimplement `bpr-try-get-project-root` function.\n\nDefault major mode for process's output buffer is `shell-mode`. Note, that this buffer is only showed in case of error, but you can manually open it at any time by `bpr-open-last-buffer`. Template for buffers names: `*process-name (process-directory)*`\n\n### Commands\n###### `bpr-spawn (cmd)`\nExecutes string CMD asynchronously in background.\n\n###### `bpr-open-last-buffer ()`\nOpens the buffer of the last spawned process.\n\n### Options\n###### `bpr-close-after-success nil`\nIndicates whether the process output window is closed on success.\n\n###### `bpr-open-after-error t`\nIndicates whether the process output window is shown on error.\n\n###### `bpr-window-creator #'split-window-vertically`\nFunction for creating window for process.\n\n###### `bpr-process-mode #'shell-mode`\nMode for process's buffer.\n\n###### `bpr-process-directory nil`\nDirectory for process.\nIf not nil, it will be assigned to default-direcotry.\nIf nil, standard default-direcotry will be used,\nor projectile-project-root, if it's available and bpr-use-projectile isn't nil.\n\n###### `bpr-use-projectile t`\nWhether to use projectile-project-root (if available) for process's directory.\n\n###### `bpr-erase-process-buffer t`\nIndicates whether the process buffer is erased at the start of the new process.\n\n###### `bpr-scroll-direction 1`\nScroll text in error window, -1 for scroll up, 1 - scroll down.\n\n###### `bpr-show-progress t`\nWhether to show progress messages for process.\n\n###### `bpr-poll-timout 0.2`\nProgress update interval.\n\n###### `bpr-colorize-output nil`\nWhether to colorize process output buffer. For this operation `ansi-color-apply-on-region' is used.\n\n###### `bpr-on-success '(lambda (process))`\nFunction which is called in case of success. If function is interactive, it's called interactively; if not, it's called in a normal way with one argument - process.\n\n###### `bpr-on-error '(lambda (process))`\nFunction which is called in case of error. If function is interactive, it's called interactively; if not, it's called in a normal way with one argument - process.\n\n###### `bpr-on-completion '(lambda (process))`\nFunction, which is always called when process is completed. If function is interactive, it's called interactively; if not, it's called in a normal way with one argument - process.\n\n### Examples for different use cases\n##### Running tests\n```elisp\n(defun my-test-runner ()\n  \"Spawns test process\"\n  (interactive)\n  (let* ((bpr-scroll-direction -1) ;; scroll to the top of the output window (which is being shown in case of error)\n         (bpr-close-after-success t)) ;; close error window after process ended successfully (if it's not already closed)\n    (bpr-spawn \"rake tests\")))\n```\n##### Running builds\n```elisp\n(defun my-build-runner ()\n  \"Spawns build process\"\n  (interactive)\n  (let* ((bpr-process-directory \"~/chromium/\") ;; spawn process in this directory (instead of default-directory or projectile-project-root)\n         (bpr-poll-timout 60.0)) ;; show progress messages once in 60 seconds\n    (bpr-spawn \"make long-build\")))\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filiabv%2Femacs-bpr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Filiabv%2Femacs-bpr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filiabv%2Femacs-bpr/lists"}