Fossil SCM
Documentation updates.
Commit
94658201c9afcefc1ec6196e1c4de813bd5fb1fc1074cb4078da2a207dc7e7b6
Parent
7e845bfd028cec4…
1 file changed
+16
-5
+16
-5
| --- www/hooks.md | ||
| +++ www/hooks.md | ||
| @@ -14,14 +14,14 @@ | ||
| 14 | 14 | * Contributions and suggestions to the hook system and/or the |
| 15 | 15 | documentation are welcomed. |
| 16 | 16 | |
| 17 | 17 | ## General Notes. |
| 18 | 18 | |
| 19 | - * Each hooks has a "type", as "sequence", and a "command". The command | |
| 19 | + * Each hooks has a "type", a "sequence", and a "command". The command | |
| 20 | 20 | is a shell command that runs at the appropriate time. The type |
| 21 | - is currently one of "after-receive", "before-commit", or "disabled". | |
| 22 | - The sequence is an arbitrary integer. | |
| 21 | + is currently one of "after-receive", "before-commit", "commit-msg", | |
| 22 | + or "disabled". The sequence is an arbitrary integer. | |
| 23 | 23 | |
| 24 | 24 | * There can be multiple hooks of the same type. When that is the |
| 25 | 25 | case, the hooks are run in order of ascending sequence. |
| 26 | 26 | |
| 27 | 27 | * Use the "fossil hook" command to create, edit, and delete hooks. |
| @@ -42,10 +42,18 @@ | ||
| 42 | 42 | |
| 43 | 43 | * The "%A" sequence becomes the name of an auxiliary input files, |
| 44 | 44 | the meaning of which depends on the hook type. The auxiliary filename |
| 45 | 45 | might be an empty string. Take care to use appropriate quoting! |
| 46 | 46 | |
| 47 | +## Disabled Hooks | |
| 48 | + | |
| 49 | + * Hooks with type "disabled" never run. They are a place-holder for | |
| 50 | + scripts that might be converted to some other hook-type later. | |
| 51 | + For example, the command "fossil hook edit --type disabled ID" | |
| 52 | + can be used to temporarily disable the hook named ID, and then | |
| 53 | + "fossil hook edit --type after-receive ID" can be used to reenable | |
| 54 | + it later. | |
| 47 | 55 | |
| 48 | 56 | ## After-Receive Hooks |
| 49 | 57 | |
| 50 | 58 | * The "after-receive" hook is run by [the backoffice](./backoffice.md) |
| 51 | 59 | whenever new artifacts are received into the repository. The artifacts |
| @@ -58,11 +66,11 @@ | ||
| 58 | 66 | invoked by backoffice, so backoffice must be running in order to |
| 59 | 67 | fire after-receive hooks. |
| 60 | 68 | |
| 61 | 69 | * The exit code from the after-receive script is ignored. |
| 62 | 70 | |
| 63 | - * The standard intput to the after-receive hook is a list of | |
| 71 | + * The standard input to the after-receive hook is a list of | |
| 64 | 72 | new artifacts, one per line. The first token on each line is the |
| 65 | 73 | hash of the new artifact. After the hash is a human-readable text |
| 66 | 74 | description of what the artifact represents. |
| 67 | 75 | |
| 68 | 76 | * Sometimes the same artifact can represent two or more things. |
| @@ -84,11 +92,14 @@ | ||
| 84 | 92 | database. |
| 85 | 93 | |
| 86 | 94 | * A push might not deliver all of the artifacts for a checkin. If |
| 87 | 95 | Fossil knows that a /xfer HTTP request is incomplete, it will defer |
| 88 | 96 | running the after-receive push for 60 seconds, or unti a complete |
| 89 | - /xfer request is received. | |
| 97 | + /xfer request is received. This helps to prevent after-receive hooks | |
| 98 | + from running when incomplete checkins exist in the repository, but | |
| 99 | + it does not provide hard guarantees, as there is no way to do that | |
| 100 | + in a distributed system. | |
| 90 | 101 | |
| 91 | 102 | * The list of artifacts delivered to standard input of the |
| 92 | 103 | after-receive hook will not contain more than 24-hours worth |
| 93 | 104 | of artifacts. If the backoffice has been shut down for a while |
| 94 | 105 | such that after-receive hooks have not been running, and more |
| 95 | 106 |
| --- www/hooks.md | |
| +++ www/hooks.md | |
| @@ -14,14 +14,14 @@ | |
| 14 | * Contributions and suggestions to the hook system and/or the |
| 15 | documentation are welcomed. |
| 16 | |
| 17 | ## General Notes. |
| 18 | |
| 19 | * Each hooks has a "type", as "sequence", and a "command". The command |
| 20 | is a shell command that runs at the appropriate time. The type |
| 21 | is currently one of "after-receive", "before-commit", or "disabled". |
| 22 | The sequence is an arbitrary integer. |
| 23 | |
| 24 | * There can be multiple hooks of the same type. When that is the |
| 25 | case, the hooks are run in order of ascending sequence. |
| 26 | |
| 27 | * Use the "fossil hook" command to create, edit, and delete hooks. |
| @@ -42,10 +42,18 @@ | |
| 42 | |
| 43 | * The "%A" sequence becomes the name of an auxiliary input files, |
| 44 | the meaning of which depends on the hook type. The auxiliary filename |
| 45 | might be an empty string. Take care to use appropriate quoting! |
| 46 | |
| 47 | |
| 48 | ## After-Receive Hooks |
| 49 | |
| 50 | * The "after-receive" hook is run by [the backoffice](./backoffice.md) |
| 51 | whenever new artifacts are received into the repository. The artifacts |
| @@ -58,11 +66,11 @@ | |
| 58 | invoked by backoffice, so backoffice must be running in order to |
| 59 | fire after-receive hooks. |
| 60 | |
| 61 | * The exit code from the after-receive script is ignored. |
| 62 | |
| 63 | * The standard intput to the after-receive hook is a list of |
| 64 | new artifacts, one per line. The first token on each line is the |
| 65 | hash of the new artifact. After the hash is a human-readable text |
| 66 | description of what the artifact represents. |
| 67 | |
| 68 | * Sometimes the same artifact can represent two or more things. |
| @@ -84,11 +92,14 @@ | |
| 84 | database. |
| 85 | |
| 86 | * A push might not deliver all of the artifacts for a checkin. If |
| 87 | Fossil knows that a /xfer HTTP request is incomplete, it will defer |
| 88 | running the after-receive push for 60 seconds, or unti a complete |
| 89 | /xfer request is received. |
| 90 | |
| 91 | * The list of artifacts delivered to standard input of the |
| 92 | after-receive hook will not contain more than 24-hours worth |
| 93 | of artifacts. If the backoffice has been shut down for a while |
| 94 | such that after-receive hooks have not been running, and more |
| 95 |
| --- www/hooks.md | |
| +++ www/hooks.md | |
| @@ -14,14 +14,14 @@ | |
| 14 | * Contributions and suggestions to the hook system and/or the |
| 15 | documentation are welcomed. |
| 16 | |
| 17 | ## General Notes. |
| 18 | |
| 19 | * Each hooks has a "type", a "sequence", and a "command". The command |
| 20 | is a shell command that runs at the appropriate time. The type |
| 21 | is currently one of "after-receive", "before-commit", "commit-msg", |
| 22 | or "disabled". The sequence is an arbitrary integer. |
| 23 | |
| 24 | * There can be multiple hooks of the same type. When that is the |
| 25 | case, the hooks are run in order of ascending sequence. |
| 26 | |
| 27 | * Use the "fossil hook" command to create, edit, and delete hooks. |
| @@ -42,10 +42,18 @@ | |
| 42 | |
| 43 | * The "%A" sequence becomes the name of an auxiliary input files, |
| 44 | the meaning of which depends on the hook type. The auxiliary filename |
| 45 | might be an empty string. Take care to use appropriate quoting! |
| 46 | |
| 47 | ## Disabled Hooks |
| 48 | |
| 49 | * Hooks with type "disabled" never run. They are a place-holder for |
| 50 | scripts that might be converted to some other hook-type later. |
| 51 | For example, the command "fossil hook edit --type disabled ID" |
| 52 | can be used to temporarily disable the hook named ID, and then |
| 53 | "fossil hook edit --type after-receive ID" can be used to reenable |
| 54 | it later. |
| 55 | |
| 56 | ## After-Receive Hooks |
| 57 | |
| 58 | * The "after-receive" hook is run by [the backoffice](./backoffice.md) |
| 59 | whenever new artifacts are received into the repository. The artifacts |
| @@ -58,11 +66,11 @@ | |
| 66 | invoked by backoffice, so backoffice must be running in order to |
| 67 | fire after-receive hooks. |
| 68 | |
| 69 | * The exit code from the after-receive script is ignored. |
| 70 | |
| 71 | * The standard input to the after-receive hook is a list of |
| 72 | new artifacts, one per line. The first token on each line is the |
| 73 | hash of the new artifact. After the hash is a human-readable text |
| 74 | description of what the artifact represents. |
| 75 | |
| 76 | * Sometimes the same artifact can represent two or more things. |
| @@ -84,11 +92,14 @@ | |
| 92 | database. |
| 93 | |
| 94 | * A push might not deliver all of the artifacts for a checkin. If |
| 95 | Fossil knows that a /xfer HTTP request is incomplete, it will defer |
| 96 | running the after-receive push for 60 seconds, or unti a complete |
| 97 | /xfer request is received. This helps to prevent after-receive hooks |
| 98 | from running when incomplete checkins exist in the repository, but |
| 99 | it does not provide hard guarantees, as there is no way to do that |
| 100 | in a distributed system. |
| 101 | |
| 102 | * The list of artifacts delivered to standard input of the |
| 103 | after-receive hook will not contain more than 24-hours worth |
| 104 | of artifacts. If the backoffice has been shut down for a while |
| 105 | such that after-receive hooks have not been running, and more |
| 106 |