fossil 基本的な使い方

fossilを使ったバージョン管理

repositoryの作成からファイルのコミット、Web UIの起動等をあっさりと。

## 環境

- Windows 10
- fossil 2.18

fossilは 一個のファイル fossil.exe だけで完結するので

本家サイトの[ダウンロード](https://www2.fossil-scm.org/home/uv/download.html)からファイルを落としてきて、
解凍してPATHの通った場所におくだけでも問題ないです。

Chocolateyが使える環境であれば 以下を管理者権限で実行してインストールでも良いです。

```batch
choco install -y fossil
```

バージョン確認するとこんな感じ

```console
D:\nodework\> fossil version
This is fossil version 2.18 [84f25d7eb1] 2022-02-23 13:22:20 UTC
```

## レポジトリの作成

hello_world.fossil というファイル名のレポジトリを作成します。

```batch
fossil new hello_world.fossil
```

fossilの repositoryは 単一のファイルです。commitされたソース・ファイル等は、
このファイルが生きていれば取り出す事が出来ます。

## 作業ディレクトリの作成・オープン

hello_world という作業ディレクトリを作成して、そこにrepositoryを開きます。

```batch
fossil open hello_world.fossil --workdir hello_world
```

現在のファイルの状態

```console
./
 │ hello_world.fossil ＜＜ repository
 └─hello_world/ ＜＜ 作業ディレクトリ（local source treeとも呼ばれます）
     └─_FOSSIL_ ＜＜ 作業ディレクトリが参照している repositoryへの path等が記録されているファイル
```

## アプリケーション作成

なんでも良いのですが、ここでは管理対象のアプリケーションサンプルとして nodeの expressを使った Hello Worldです。
nodeのインストールは別途しておいてください。

ここから 作業ディレクトリのルート上で操作していきます。

```batch
cd hello_world
```

npmで initして expressを install

```batch
npm init -y
npm install express --save
```

この時点でこんな感じのファイルやフォルダが作られます。

```console
./
│ hello_world.fossil
└─hello_world
    │ package-lock.json ＜＜管理対象にしたいファイル
    │ package.json ＜＜管理対象にしたいファイル
    │ _FOSSIL_
    └─node_modules ＜＜管理対象に入れる必要の無いファイル郡
```

## fossil extras: バージョン管理されていないファイルの確認

作業ディレクトリ配下で 新規に追加されたファイル＝バージョン管理をしていないファイルを確認します。

```batch
fossil extras
```

実行すると express 関係のファイルが node_modules 以下にあって大量に出てしまうと思います。

```console
D:\nodework\hello_world>fossil extras
node_modules/accepts/HISTORY.md
... たくさんのファイル ...
node_modules/vary/README.md
package-lock.json
package.json
```

node_modules 以下は管理する必要がないので、設定をして無視するようにします。

## .fossil-settings/ignore-glob: バージョン管理から無視するファイル／フォルダの設定

gitの場合 .gitignore ファイルを書きますが、fossilの場合 2つ方法があります。

- fossil settings ignore-glob コマンドで、レポジトリに対して無視するファイル名の規則を設定する
- .fossil-settings/ignore-glob ファイルに無視するファイル名の規則を設定する

[glob] なので具体的な名前と ワイルドカード * と ? を使ってファイル郡を設定します。
ただ、[fossilのglob]は パス区切り文字も含めてワイルドカードがマッチする点がちょっと違います。

ここでは後者。設定ファイル .fossil-settings/ignore-glob を repository に追加して管理していくことにします。

```text:.fossil-settings/ignore-glob
## 無視するファイル名
node_modules
```

ここで もう一度 `fossil extras` を実行すると今度は node_modules が無視されてぐっとファイル数が減ると思います。

```console
D:\nodework\hello_world>fossil extras
package-lock.json
package.json
```

ただ、設定ファイルの .fossil-settings/ignore-glob ファイルも出てきません。

fossilはデフォルトで . (ドット) で始まるファイルは明示的に指定されない限り無視します。
このため、.fossil-settings/ignore-glob も無視されてしまったというわけです。

こういう時は `--dotfiles` オプションで 対象に含める事が出来ます。

```console
D:\nodework\hello_world>fossil extras --dotfiles
.fossil-settings/ignore-glob
package-lock.json
package.json
```

ここで表示されたファイルは バージョン管理されていないので repositoryに追加して管理するようにします。

[glob]: https://linuxjm.osdn.jp/html/LDP_man-pages/man7/glob.7.html
[fossilのglob]: https://fossil-scm.org/home/doc/trunk/www/globs.md

## fossil add: バージョン管理対象の追加

まずは package.json をバージョン管理対象に含める様に指定します。

```batch
fossil add package.json
```

これで repository に追加する対象として package.json ファイルがマークされます。
この後 commit によりレポジトリ内に マークされたファイルが取り込まれます。

なお、git の staging とは違いますので、一度 addしてしまえば、変更する度に毎回 `git add -u` する必要はありません。

## addremove: 作業ディレクトリに存在する新規ファイル／消えたファイルをまとめて登録削除

gitで言うと `git add -A` と同じ様な感じ。

extrasコマンドで管理対象に含められていないファイルの一覧がわかっていますし、全部管理対象にしておきたい場合は一つのコマンドでまとめて追加削除できます。ここでも `--dotfiles` を付ける事で ドットで始まるファイルも対象にできます。

```batch
fossil addremove
fossil addremove --dotfiles
```

いきなりやると余計なファイルが入ってしまう事もありますので、実際の変更を加えない dry-run (-n) オプションを指定して確認します。

```bash
fossil addremove --dotfiles -n
```

(dry-runでも同じ表示ですが) 実際にファイルを追加すると 以下のような表示がされます。

```console
D:\nodework\hello_world>fossil addremove --dotfiles
ADDED  .fossil-settings/ignore-glob
ADDED  package-lock.json
ADDED  package.json
added 3 files, deleted 0 files
```

現状の バージョン管理対象としてはこれで良いので次に進みます。

## status: 現在の作業ディレクトリの状況の確認

現在の作業ディレクトリで、ファイルの追加・削除・変更状況等を確認します。

```batch
fossil status
```

結果はこんな感じ。

```console
D:\nodework\hello_world>fossil status
repository:   D:/nodework/hello_world.fossil
local-root:   D:/nodework/hello_world/
config-db:    C:/Users/yasuo/AppData/Local/_fossil
checkout:     d673096bb32cf540370edb48817f7e8d0c05046b 2021-05-11 07:38:18 UTC
tags:         trunk
comment:      initial empty check-in (user: yasuo)
ADDED      .fossil-settings/ignore-glob
ADDED      package-lock.json
ADDED      package.json
```

チェックアウトしたバージョンや 作業ディレクトリに入っている変更を確認出来ます。

## commit: 変更を取り込む

```batch
fossil commit
```

この場合ファイル指定がないので変更全てを取り込みます。

変更した特定のファイルだけ commitしたい場合、 gitの場合 addで staging してから、commit しますが、fossilの場合は commit 時に取り込みたいファイルを指定する形になります。

例えば、package.json の変更だけを commitしたい場合は

```batch
fossil commit package.json
```

といった形です。

実行するとこんな形で新しいVersionが表示されます。

```console
D:\nodework\hello_world>fossil commit -m "wip"
New_Version: 4bcc464539824bf123c7d8f7d1ced8c6ed9e32fe6c5366f70c23f19ee9740ee3
```

なお、commitしたときに 色々fossilはお節介をやいてきます。

- commitのコメントが無いときはエディタ起動
- 改行コードがDOS(CR/LF)のファイルを見つけたときは変換の確認(crlf-glob設定で無視可能)
- テキストファイルの encodingが utf-8でも asciiでもないと判断された場合の確認(encoding-globで無視可能)
- textファイル扱いだが binaryファイルのように思われるファイルの確認(binary-globで binaryファイルを明示可能)
- commitすると forkしてしまうケースでの updateの推奨
- remote repository(上流)との autosync (pull/push)実施

これらは settings や設定ファイル(binary-glob/crlf-glob等)で 動作を変えられます。

## ui: Web UIの起動

作業ディレクトリで `fossil ui` を実行すると Web UIが起動します。

```console
D:\nodework\hello_world>fossil ui
Temporary files: C:\Users\xxxxxx\AppData\Local\Temp\fossil_server_P8080*
Listening for HTTP requests on TCP port 8080
Launch webbrowser: start http://localhost:8080/timeline?c=current &
Type Ctrl-C to stop the HTTP server
```

Timelineが表示されるかと思います。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/128512/840cc6fd-a9ed-ff4b-9362-8cf98c51739c.png)

蛇足かと思いますが、黒系の画面なのは Ardoise の Skinを指定しているためです。
Skinは [http://localhost:8080/setup_skin_admin](http://localhost:8080/setup_skin_admin)にアクセスすると変更できます。
Admin → Skins に行くとカスタマイズ方法が出てくるのですが、ありもので簡単に切り替える場合は この方法で変えるのが楽かと思います。

なお、`fossil server`で Fossilサーバを起動出来るのですが、UIと見た目が ほぼ同じです。
ただし下記が異なります[^ui]。

- UIは外部からの接続不可 - localhost(IPv4/IPv6)で Listen
- UIはBrowserを自動的に起動
- UIは現在のユーザ[^user]でログインした状態で起動
- UIはtimelineが表示される

作業PC上での作業の場合、サーバポートを開ける必要は無いと思いますので 通常は ui で起動すべきかと思います。

[^user]: 通常fossil new したときに setup ユーザとして、Windowsアカウントのユーザ名でユーザが自動作成されていると思います。
[^ui]: これ以外にもあるかもしれません。 ui と server は ブラウザが自動起動するかしないかだけ！という解説も多いのですが、少なくともListenするサーバIPが異なる点はセキュリティ上意識したほうが良いと思います。

## その他UI関連設定

ファイルをバージョン管理するだけなら、こんなもんで大体使い始められると思うのですが
ここら辺は設定したほうが良いかも？という点だけ紹介

### プロジェクト名の設定

uiの Admin → Configurationを開いて 一番上 Project Nameを設定して Apply

### プロジェクトホームページに表示する情報の設定

1. プロジェクト名を設定
2. uiの Wiki → New から プロジェクト名 の Wikiページを作る(Markup Styleは お好きに)

githubに慣れている方だと ルートにある README.mdを表示したい！と思うと思います。

その場合には

1. README.md を addして commitする
2. uiの Admin → Configuration の Index Page という項目を /home → /doc/tip/README.md と変更して Apply

## 最後に

こんな感じでfossilを使い始める事が出来るかと思います。
本当はTicketとかについても触ろうかと思いましたが、長くなるのでまた今度。

あ、expressの hello world忘れてた……