import_path_converter(Flutterパッケージ)の紹介と使い方例

はじめに

import_path_converterというパッケージを作成してpub.devに公開したので、その紹介と実用的な使い方について紹介したいと思います。

https://pub.dev/packages/import_path_converter

GitHubのリポジトリはこちらです。
https://github.com/ymgn9314/import_path_converter

どういうパッケージか

import_path_converterは、相対パスのインポートとパッケージパスのインポートを自動で変換するツール系パッケージです。

使い方は簡単で、パッケージのインストールを行った後に以下のコマンドを実行するだけでdartファイルのインポートが変換されます。

flutter pub run import_path_converter:main

例えば、このような相対パスでインポートしているファイルの場合、

import 'common/constants.dart';
import '../app.dart';

このようにパッケージパスのインポートに変換されます(逆への変換も可能です)。

import 'package:example/common/constants.dart';
import 'package:example/app.dart';

インストール方法と設定について

インストールは下記のようにdev_dependenciesに追加するだけです。

dev_dependencies:
  import_path_converter: ^1.0.1

pubspec.yamlに以下のような設定を書くことで、相対パスに変換するかパッケージパスにするかを変更できたり、変換させないファイルを指定できたりします。

import_path_converter:
  relative: true # true->相対パスに変換, false->パッケージパスに変換(デフォルト: false)
  ignored_files: # 無視するファイルを正規表現で記述(デフォルト: [])
    - \/lib\/*

その他の使い方は、ドキュメントをご参照ください。

実用的な使い方について

このパッケージを作った目的は、チーム開発時のインポートの表記ブレを防ぐためです。

インポート順や、インポートパスの表記が人によってブレてしまうと、Gitに差分として表示されてしまったり、レビューで指摘をする必要がでてきてしまい、かなりの負担になってしまいます。

この問題を解決するために、GitのGit Hooksという機能を使ってgit commit時にフォーマットを自動実行する方法について紹介したいと思います。

その前に...

今回紹介する方法では、import_sorterというパッケージも合わせて使うため、先にインストールしておいてください。
(ちなみにimport_path_converterはimport_sorterをフォークして作りました。)

https://pub.dev/packages/import_sorter

Git Hooks(pre-commit)のファイルを作成

Git Hooksの設定は簡単で、プロジェクトのルートにある、.git/hooksに以下のファイルをpre-commitという名前で配置します。

#!/bin/sh

# Stageにある拡張子がdartのファイルをforループする
for FILE in `git diff --staged --name-only --diff-filter=AM | grep -e .dart`; do
    # もし.dart以外の拡張子に対しても何か処理を行いたい場合は、次のように拡張子で判別する
    # また、for文のgrep箇所を、grep -e .py -e .dart のように複数拡張子を指定することもできる
    # if [ ${FILE##*.} = "js" ]; then
    # fi

    # excec import_path_converter
    echo "Running import_path_converter..."
    flutter pub run import_path_converter:main $FILE

    # excec import_sorter
    echo "Running import_sorter..."
    flutter pub run import_sorter:main $FILE

    # excec flutter format
    echo "Running flutter format..."
    flutter format $FILE

    git add $FILE
done

これだけで、git commit時にimport_sorterとimport_path_converter、flutter formatの3つが自動で実行されるようになります。

つまり、git pushされるファイルは全てフォーマット後のファイルのみになるということです。

Git Hooksの設定をローカルにコピーするスクリプトを作成

Git Hooksの設定は.git/hooksにあるため、git管理はできません。

そのため、Git Hooksの設定をローカルにコピーするスクリプトを用意しておいて全員共通の設定を使うようにするといいでしょう。

以下はその例です。

上記のpre-commitをscript/git_hook/に配置してGitで管理しておきます。

以下のシェルスクリプトはscript/copy_git_hook.shとしました。

DSTDIR=.git/

if [ ! -d $DSTDIR ]; then
    echo ".git/ directory not found. Please move to project root."
    exit 1
fi

cp script/git_hook/pre-commit .git/hooks
chmod +x .git/hooks/pre-commit

echo "Successfully copied!"

その上で以下を実行すると、ローカルの.git/hooksに設定ファイルがコピーされます。

chmod +x script/copy_git_hook.sh
./script/copy_git_hook.sh

プロジェクトのセットアップ時に開発メンバー全員にGit Hooksの設定を行ってもらうようにするとかなり効果的かと思います。

追記(2021/11/02)

この記事についてTweetしたところ、@sugitlab さんからこんな情報をいただきました！

https://twitter.com/sugitlab/status/1455492681384140810?s=20

このルールをanalysis_options.yamlに書くことで、相対パスでインポートしている箇所に警告を出してくれるようになります。

https://dart-lang.github.io/linter/lints/avoid_relative_lib_imports.html

最後に

ここまで読んでくれてありがとうございました！

もしバグ等あれば、GitHubに報告をもらえると助かります！

参考文献

• コミット前に自動でフォーマットを整える設定をgit管理して、リポジトリ全体でフォーマットを統一する

• pre-commitでこんな自動レビューをしています！手戻りが少なくて最高！