Append-once.mw

{{Header}}
{{title|title=
append/append-once/overwrite
}}
{{#seo:
|description=The <code>append</code>, <code>append-once</code>, and <code>overwrite</code> utilities safely append a line to a file. <code>append</code> appends a line unconditionally, <code>append-once</code> appends a line only if the line isn't present in the file already, and <code>overwrite</code> overwrites the entire contents of the file with the provided line. The scripts feature sanity checks, atomic write operations, and a simplified interface.
}}
{{intro|
How to use the <code>append</code>, <code>append-once</code>, and <code>overwrite</code> to append and replace data in files.
}}

= Introduction =
[https://github.com/Kicksecure/helper-scripts/blob/master/usr/bin/append <code>append</code>]:

* Appends a user-provided line to a text file.
* Includes additional sanity testing (checks if the folder where the file resides is writable; checks if the file is readable and writable).
* Offers an easier-to-use interface. <ref>
[1] No need to use:

* <code>grep</code>
* considering special characters in <code>grep</code>
* <code>printf</code>
* pipe
* <code>readlink</code>
* <code>>/dev/null</code> redirection.
</ref>
* Write operations are atomic.
* If called as <code>append-once</code>, it avoids duplicating the same content, should the exact same lines have already been appended earlier.<ref><code>append-once</code> was previously implemented as a standalone Bash script, while <code>append</code> and <code>overwrite</code> did not exist. The new implementation is written in Python, fixes limitations, improves error and edge case handling, and provides the two additional utilities.</ref>
* If called as <code>overwrite</code>, replaces all of the contents of the file with the provided line.
* Its write operation is similar to:

<pre>
printf "%s\n" "text to append" | sponge -a /file/to/append/to >/dev/null
</pre>

<code>append</code> is the primary executable. The <code>append-once</code> and <code>overwrite</code> executables are simply symlinks to <code>append</code>. <code>append</code> will check what executable it was called as, and adjust its behavior accordingly.

= Target Audience =
{{AdvancedUsersOnly}}

If <code>append</code>, <code>append-once</code>, or <code>overwrite</code> are used in a security critical context, it should only be used by people capable of reviewing its relatively short and simple source code.

= Syntax =
<pre>
(append|append-once|overwrite) /path/to/file 'line to append'
</pre>

= Example =
{{CodeSelect|code=
append ~/testfile 'some text here'
}}

= Exit Codes =
* 0: Success.
* Non-Zero: Failure.

= Limitations =
* None known at the time of this writing.

= Footnotes =
<references />
[[Category:Documentation]]
{{Footer}}