1 files changed, 86 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6113d3c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,86 @@
+<!--
+SPDX-License-Identifier: GPL-3.0-only
+SPDX-FileCopyrightText: 2025 M. Shulhan <ms@kilabit.info>
+-->
+
+# spdxconv
+
+spdxconv is a tool to convert and insert the SPDX license headers.
+
+## Background
+
+Converting the license and copyright in the source codes to become compliant
+with the SPDX headers is very tedious works, especially if we have so many
+files with different year, copyright, and licenses.
+
+This program help to do that by using pattern-matching, search, replace, and
+sometimes deletion.
+
+## Usage
+
+The first thing to do is to generate the configuration file using
+
+```
+$ spdxconv init
+```
+
+This will create the `spdxconv.cfg` file in the current directory with the
+following content,
+
+```
+[default]
+license_identifier =
+file_copyright_text =
+max_line_match = 10
+
+[match_license]
+pattern = ^(//+|#+)*\s+(.*)governed by a BSD-style(.*)$
+license_identifier = BSD-3-Clause
+delete_match = true
+delete_line_pattern = ^(//+|#+)*\s+license that(.*)$
+
+[match_copyright]
+pattern = ^(//+|#+)*\s+Copyright\s+(?<year>\d{4},?\s+(?<holder>.*)\s+<*(?<email>.*)>.*$
+```
+
+The next subsection explain each of this section in the configuration file.
+
+### default section
+
+First is the `[default]` section.
+This section define the default license identifier and copyright text to be
+inserted into file if no match_license or match_copyright found on the file.
+You should fill the `license_identifier` and `file_copyright_text` before
+continue running the program.
+
+The `max_line_match` define the number of lines to be searched at the
+top and bottom of file for match_license and match_copyright before the
+program insert the default values.
+
+### match_license section
+
+The first thing that the program do is search for line that match
+"SPDX-License-Identifier:".
+
+If there is a match, at the top or bottom, the scan will stop.
+
+If there is no match it will search for a line that match with "pattern"
+regular expression.
+If there is a line that match with it, the value in
+"match_license::license_identifier" will replace the
+"default::license_identifier" value.
+If the "delete_match" is true, it will delete the line from the file.
+If there is "delete_line_pattern" defined, it will search for line that match
+with that regular expression and delete it.
+The "delete_line_pattern" can be defined zero or more times.
+
+## References
+
+[SPDX License List](https://spdx.org/licenses/).
+The SPDX License List includes a standardized short identifier, the full
+name, the license text, and a canonical permanent URL for each license and
+exception.
+
+[REUSE FAQ](https://reuse.software/faq/).
+This page lists common questions and their answers when dealing with
+licensing and copyright, and with the adoption of REUSE specifically.