angular / gulp-clang-format Goto Github PK

License: Apache License 2.0

JavaScript 99.61% TypeScript 0.39%

gulp-clang-format's Introduction

gulp-clang-format

Gulp plugin to check that code is properly formatted, according to clang-format.

If the code differs from how clang-format would format it, this prints a warning to the build output, as well as a command to run that formats the file in-place.

Usage

Sample gulpfile.js:

var format = require('gulp-clang-format');

var srcsToFmt = ['path/**/*.js'];

gulp.task('check-format', function() {
  return gulp.src(srcsToFmt)
     .pipe(format.checkFormat());
});

gulp.task('format', function() {
  // The base option ensures the glob doesn't strip prefixes
  return gulp.src(srcsToFmt, {base: '.'})
      .pipe(format.format())
      .pipe(gulp.dest('.'));
});

Promoting warnings to errors

If you want to enforce the formatting, so that other team members don't introduce code that gives you a warning, you can turn them into build errors by acting on the 'warning' event. For example, this task exits the build immediately:

var format = require('gulp-clang-format');

gulp.task('check-format', function() {
  return gulp.src('*.js')
      .pipe(format.checkFormat('file'))
      .on('warning', function(e) {
        process.stdout.write(e.message);
        process.exit(1);
      });
});

Options

The format() and checkFormat() both accept two options: opt_clangStyle and opt_clangFormat. checkFormat() also accepts a third option, opt_gulpOptions.

opt_clangStyle

An optional parameter indicating the clang-format style to use. By default, it applies the "Google" style.

The parameter is passed to the -style argument of clang-format. See the docs here: http://clang.llvm.org/docs/ClangFormatStyleOptions.html

The recommended value is the string 'file', this means that clang-format will look for a .clang-format file in your repository. This allows you to keep the formatting consistent with other developers.

opt_clangFormat

The resolved clang-format module to use. Useful to pass a specific clang-format version to the task.

var format = require('gulp-clang-format');
var clangFormat = require('clang-format');

gulp.task('check-format', function() {
  return gulp.src('*.js')
      .pipe(format.checkFormat('file', clangFormat));
});

opt_gulpOptions

Options for the gulp operation. Supported options are

verbose, which causes a diff of all changed files to be printed.
fail, which causes the task to emit an error instead of a warning.

var format = require('gulp-clang-format');

gulp.task('check-format', function() {
  return gulp.src('*.js')
      .pipe(format.checkFormat(undefined, undefined, {verbose: true, fail: true}));
});

gulp-clang-format's People

Contributors

Stargazers

Watchers

Forkers

alan-agius4 devversion isabella232

gulp-clang-format's Issues

Sporadic false positives due to stream-equal 0.1.7

When upgrading transitive dependencies of gulp-clang-format in angular/angular I started seeing frequent but random false positives when running gulp check-format.

I was able to narrow the issue down to gulp-clang-format's stream-equal dependency. Version 0.1.6 works just fine but 0.1.7 exhibits this problem.

I haven't investigated if this is happening due to a bug in stream-equal or due to how we use it.

For now I'm going to limit the stream-equal transitive dependency of gulp-clang-format to <=0.1.6.

format() does not change the file modification time

const clangFormat = require('gulp-clang-format');
const gulp = require('gulp');

gulp.task('format', () =>
{
	let src = 'src/**/*.cpp';

	return gulp.src(src, { base: '.' })
		.pipe(clangFormat.format('file'))
		.pipe(gulp.dest('.'));
});

Runnin the gulp format task achieves its purpose and modifies source files according to rules in .clang-format. But, the modification time of those modified files do not change.

This is annoying when you have such a file into a text editor, run gulp format in a terminal, the file is modified, but the text editor has no way to realize of it so the display is not refreshed.

As a suggestion, format() may invoke touch in modified files.

P.S.: This may be an issue of clang-format itself.

version skew when running suggested command

When the formatting is not correct, we print a clang-format command line for how to fix it.
That relies on the version of clang-format installed globally by npm, which may differ from the version used in the project's node_modules.
As a result, the formatting produced by running the command may not fix the warnings from the gulp build. We should print a command line which uses the same version as gulp task will use.

format check fails even though clang-format is happy

broccoli-typescript.ts keeps on failing the gulp check-format task in angular/angular even after the file has been formatted with clang-format and rerunning clang-format yields zero delta.

is it possible that the way the two streams are compared is not always reliable?

Overwrite code

Instead of providing a formatted directory, is it possible to overwrite the files instead?

Thanks