// vim:set filetype=asciidoc:
[[sanitize]]
== Sanitization of the source

There are a few cases which require to sanitize the source to prevent contaminating the generated Debian source package.

* Non https://www.debian.org/social_contract.html#guidelines[DFSG] contents in the upstream source.
** Debian takes software freedom seriously and follows the https://www.debian.org/social_contract.html#guidelines[DFSG].
* Extraneous auto-generated contents in the upstream source.
** Debian package should rebuild them under the latest system.
* Extraneous VCS contents in the upstream source.
** The *-i* and *-I* options set in "`<<devscripts-setup>>`" for the *dpkg-source*(1) command should avoid these.
*** The *-i* option is aimed at the non-native Debian package.
*** The *-I* is aimed at the native Debian package.

There are several methods to avoid inclusion of undesirable contents.

[[files-excluded]]
=== Fix with *Files-Excluded*

This is suitable for avoiding non https://www.debian.org/social_contract.html#guidelines[DFSG] contents in the upstream source tarball.

* List the files to be removed in the *Files-Excluded* stanza of the  *debian/copyright* file.
* List the URL to download the upstream tarball in the *debian/watch* file.
* Run the *uscan* command to download the new upstream tarball.
** Alternatively, use the "`*gbp import-orig --uscan --pristine-tar*`" command.
* *mk-origtargz* invoked from *uscan* removes excluded files from the upstream tarball and repack it as a clean tarball.
* The resulting tarball has the version number with an additional suffix *+dfsg*.

See "`*COPYRIGHT FILE EXAMPLES*`" in *mk-origtargz*(1).

[[rules-clean]]
=== Fix with "`*debian/rules clean*`"

This is suitable for avoiding auto-generated files and removes them in the "`*debian/rules clean*`" target

NOTE: The "`**debian/rules clean**`" target is called before the "`**dpkg-source --build**`" command by the **dpkg-buildpackage** command and the "`**dpkg-source --build**`" command ignores removed files.

[[extend-diff-ignore]]
=== Fix with *extend-diff-ignore*

This is for the non-native Debian package.

The problem of extraneous diffs can be fixed by ignoring changes made to parts of the source tree by adding the "`**extend-diff-ignore=...**`" line in the **debian/source/options** file.

.**debian/source/options** to exclude the *config.sub*, *config.guess* and *Makefile* files:
----
# Don't store changes on autogenerated files
extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"
----

NOTE: This approach always works, even when you can’t remove the file. So it saves you having to make a backup of the unmodified file just to be able to restore it before the next build.

TIP: If the *debian/source/local-options* file is used instead, you can hide this setting from the generated source package.  This may be useful when the local non-standard VCS files interfere with your packaging.

[[tar-ignore]]
=== Fix with *tar-ignore*

This is for the native Debian package.

You can exclude some files in the source tree from the generated tarball by tweaking the file glob by adding the "`**tar-ignore=...**`" lines in the **debian/source/options** or **debian/source/local-options** files.

NOTE: If, for example, the source package of a native package needs files with the file extension *.o* as a part of the test data, the setting in "`<<devscripts-setup>>`" is too aggressive.  You can work around this problem by dropping the *-I* option for *DEBUILD_DPKG_BUILDPACKAGE_OPTS* in "`<<devscripts-setup>>`" while adding the "`**tar-ignore=...**`" lines in the *debian/source/local-options* file for each package.

[[git-clean]]
=== Fix with "`*git clean -dfx*`"

The problem of extraneous contents in the second build can be avoided by restoring the source tree by committing the source tree to the Git repository before the first build.

You can restore the source tree before the second package build.  For example:

----
 $ git reset --hard
 $ git clean -dfx
----

This works because the *dpkg-source* command ignores the contents of the typical VCS files in the source tree with the *DEBUILD_DPKG_BUILDPACKAGE_OPTS* setting in <<devscripts-setup>>.

TIP: If the source tree is not managed by a VCS, you should run "`**git init; git add -A .; git commit**`" before the first build.

