From 69199ed2b7b14e92536cb439bcd23e13e775f10b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Mon, 29 Dec 2014 18:58:37 +0100 Subject: [PATCH] more copyediting of the docs --- pre-receive-reject-binaries | 36 +++++++++++++++++++++++++----------- 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/pre-receive-reject-binaries b/pre-receive-reject-binaries index 0d4ac0c..7c4d5b8 100755 --- a/pre-receive-reject-binaries +++ b/pre-receive-reject-binaries @@ -48,7 +48,8 @@ pre-receive-reject-binaries - A configurable Git hook to intelligently reject bi This is a Git hook meant to be set up as a C hook (see C) that'll reject the addition of binary data to a -repository, either all binary additions if they go above a given size. +repository, either all binary additions if they on a per-commit basis +go above a given size. The general strategy of this hook is that when we get a push for a given "master" branch we'll do a C of C<$branch..$to> and @@ -56,13 +57,26 @@ find all the commits that add binary data, and how much they add. Each commit in the push is then given a quota of how much binary data is allowed, if any commit goes above that quota the entire push is -rejected, depending on the configuration (see below) the user is +rejected. Depending on the configuration (see below) the user is allowed to force the push to go through by amending the commit message to include some string saying they forced it through. -To entirely reject binary pushes the size limit can be set to 0, but -you can also allow some amount of binary data in the repository, -e.g. to allow committing small icons but not giant images. +To entirely reject binary pushes you can set the size limit to 0 and +don't define an override message to allow users to push those changes +manually. + +You can also allow some amount of binary data in the repository +per-commit, e.g. to allow committing small icons but not giant images. + +Of course someone could be clever and commit a bunch of huge +Base64-encoded data that wouldn't be detected by Git as binary, or +manually split up huge binary data into multiple commits, each of whom +don't go above the configured limit. + +This hook is not meant to stop a dedicated attacker from enlarging +your Git history, it's meant to stop someone who doesn't know better +("what do you mean people have to download my binary data on every +checkout, forever?!") from accidentally messing up the history. We only care about updates to the "master" branch for two reasons, one is that if you're e.g. doing some temporary work and committing some @@ -87,8 +101,9 @@ validating the entire history being pushed. =head1 INSTALLATION Our only dependencies are a working perl interpreter. We only depend -on modules that have shipped with perl itself forever, so we should -Just Work on any *nix-like OS that has perl installed. +on modules that have shipped with perl itself forever, so this hook +should just work out of the box on any *nix-like OS that has perl +installed. To enable it for a given bare repository you want to push to just create a F with something like: @@ -96,10 +111,9 @@ create a F with something like: #!/bin/sh /path/to/where/you/cloned-pre-receive-reject-binaries/pre-receive-reject-binaries --dry-run=0 -See L below for how to configure it. We just shell out -to C so you can enable this configuration per-repository, -or globally (via e.g. F) or any combination of the -two. +See L below for how to configure it. We shell out to +C so you can enable this configuration per-repository, or +globally (via e.g. F) or any combination of the two. =head1 CONFIGURATION