{"id":26151943,"url":"https://github.com/abougouffa/virtual-format","last_synced_at":"2025-08-08T17:20:30.264Z","repository":{"id":249890090,"uuid":"832855078","full_name":"abougouffa/virtual-format","owner":"abougouffa","description":"Format buffers visually without modification","archived":false,"fork":false,"pushed_at":"2024-08-01T18:05:19.000Z","size":263,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-08-02T18:40:35.596Z","etag":null,"topics":[],"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":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abougouffa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-23T21:25:57.000Z","updated_at":"2024-08-01T18:05:22.000Z","dependencies_parsed_at":"2024-08-01T18:05:03.669Z","dependency_job_id":null,"html_url":"https://github.com/abougouffa/virtual-format","commit_stats":null,"previous_names":["abougouffa/visual-format"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abougouffa%2Fvirtual-format","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abougouffa%2Fvirtual-format/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abougouffa%2Fvirtual-format/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abougouffa%2Fvirtual-format/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abougouffa","download_url":"https://codeload.github.com/abougouffa/virtual-format/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242988048,"owners_count":20217538,"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":[],"created_at":"2025-03-11T06:55:14.032Z","updated_at":"2025-03-11T06:55:14.639Z","avatar_url":"https://github.com/abougouffa.png","language":"Emacs Lisp","funding_links":[],"categories":[],"sub_categories":[],"readme":"Virtual Format\n==\n\nThis package provides a simple mode to visually format buffers without modifying\nthem.\n\n\n### Motivation\n\nWhen working on big and dirty projects, we usually face the problem of badly\nformatted source files (mixed tabs and spaces, messy indentation, inconsistent\ncode formatting, etc.)\n\nThe trivial (and naive) way of dealing with this kind of problems is to format\nthe files and commit them to the central repository. However, in real world\nprojects, it is not that simple!\n\nI found myself working on some complex projects and with dirty formatting! So,\nEmacs being Emacs, I know that I can do something to format the buffer visually\nwithout actually modifying it. I've looked-up but didn't find a package that\ndoes this.\n\n### Example\n\nHaving this dirty code at the left side, it becomes like the one on the right\nside after calling `virtual-format-buffer`:\n\n![Before and after virtually formatting the buffer](etc/virtual-format.png \"Left: before virtually formatting the buffer, right: after\")\n\n### Basic usage\n\nTLDR; you can use this package in one of the three scenarios:\n\n1. You can call `virtual-format-buffer`, `virtual-format-region` or\n   `virtual-format-mode` to virtually format the current buffer/region. If the\n   command succeeds, the buffer becomes formatted while you can modify the\n   buffer without affecting the original formatting.\n2. If the former commands failed to format the buffer, you can try the\n   `virtual-format-buffer-incrementally`, this command will try to format code\n   blocks from the top-level, and when a block fails, it tries to format each\n   sub-block independently. Please note that this strategy is quite slow and can\n   fail for some languages.\n3. As a last resort, in order to **view** a buffer as formatted without\n   modifying it. You can call the `virtual-format-view-mode`, this mode is very\n   simple, it only calls the formatter and displays the formatted buffer as\n   read-only. No fancy stuff are performed (actually, we don't even need Tree\n   Sitter for this mode).\n\n### How it works?\n\nThe idea behind this package is quite simple, for a target buffer, it creates a\ntemporary buffer with the same content and formats it with the formatter of your\nchoice (customize it via `virtual-format-buffer-formatter-function`). Then,\ntransposes the spaces and newlines from the formatted buffer to the original\nbuffers via Emacs' _text properties_.\n\nIn order to know where to look, `virtual-format` uses Tree Sitter (via Emacs 29+\n`treesit`), it walks the AST for the original buffer and the formatted buffer to\nthe token level, and then, it copies the spaces/newlines between the tokens from\nthe formatted buffer to the original one. What we mean here by *copying* is the\nfact that Emacs will **display** the spaces present in the original buffer\n**as** the spaces observed in the formatted buffer, hence, you don't change the\nbuffer content and we still have editing access to the code in between. This\nmeans that, when editing and saving virtually formatted buffer, we will not\nchange the formatting, only the manually edited part gets written to the file.\n\n#### Assumptions\n\nFor `virtual-format-region` and `virtual-format-buffer`, the following\nassumption has to be verified:\n\n\u003e [!CAUTION]\n\u003e The formatted buffer **should** have the same AST as the original buffer\n\nIn other words, if the used formatter adds some instructions the original code,\nlike replacing an `if-else` with a `switch-case` or something similar.\n\nSometimes, depending on the buffer being formatted or not, Tree Sitter might\nproduce a buggy AST (in such cases, you should report the issue in the\ncorresponding Tree Sitter grammar repository). This can make the virtual\nformatting fail, in this case, you can set the\n`virtual-format-keep-incomplete-formatting` to non-nil in order to keep the\nformatted regions. If you want to see where the formatting has failed, you can\nset `virtual-format-jump-on-incomplete-formatting` so the point (cursor) jumps\nto the problematic position when the error occurs.\n\nThese issues can also happen when the used formatter modifies the code\nsignificantly.\n\n\u003e [!IMPORTANT]\n\u003e In both cases, you can try to invoke `virtual-format-buffer-incrementally` so\n\u003e `virtual-format` does its best to format the buffer.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabougouffa%2Fvirtual-format","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabougouffa%2Fvirtual-format","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabougouffa%2Fvirtual-format/lists"}