https://github.com/d-e-s-o/cformat
https://github.com/d-e-s-o/cformat
Last synced: 10 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/d-e-s-o/cformat
- Owner: d-e-s-o
- License: gpl-3.0
- Created: 2022-06-27T15:29:21.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2022-07-16T06:49:15.000Z (over 3 years ago)
- Last Synced: 2025-02-28T12:43:57.383Z (10 months ago)
- Language: Rust
- Size: 18.6 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
cformat
=======
Purpose
-------
**cformat** is a program for conveniently formatting changes made to C or
C++ files using `clang-format`. Contrary to most formatters, the program
allows for *incremental* reformatting of files. That is, when lines in a
file are changed they and only they will be reformatted (optionally with
some context), while the remainder of the file will be preserved as-is.
Such behavior can be tremendously useful in incrementally migrating over
a code base to being formatted in an automated fashion.
Given that the program is merely a wrapper around
[`clang-format`][clang-format], it automatically picks up the
corresponding configuration.
Usage
-----
**cformat** interprets a patch in unified diff format and infers files and
changed lines based on it. This patch is read from standard input.
While not at all tied to `git`, we use it here for illustration purposes
(and because it is likely the context in which the program will be
used).
To simplify usage, we introduce a ``git`` alias (``git cfp`` -- *"c
format patch"*) that retrieves any currently staged changes and pipes
them to the program. An alias for annotating the currently staged
changes could look like this:
```git
[alias]
cfp = "!cfp() { git diff --no-prefix --relative --staged --unified=0 \"$@\" | cformat; }; cfp"
```
Once you have staged changes, you can run `git cfp` and affected lines
will get reformatted according to `clang-format`'s rules.
Three aspects of the above definition are of particular relevance here:
- `--no-prefix` is important to make sure that paths contained in
emitted diffs do not contain any `a/` prefixes but map right to files
in the file system
- `--relative` is necessary because without it `git` emits file names
relative to the repository root, whereas `cformat` may be invoked from a
sub-directory, in which case paths would not necessarily map to files
- `--unified=0` ensures that only lines that were actually touched are
reformatted, as opposed to lines contained in the context that is used
for fuzzy matching; increase the context to format additional lines
surrounding changes
Installation
------------
**cformat** is written in Rust and requires the Cargo package manager to be
built. It can be installed using `cargo install cformat`. It relies on
`clang-format` being installed and runnable.
[clang-format]: https://clang.llvm.org/docs/ClangFormat.html