|
1
|
<title>Deleting Content From Fossil</title> |
|
2
|
|
|
3
|
<h2>Good Reasons for Removing Content from a Fossil Repository</h2> |
|
4
|
|
|
5
|
Fossil is designed to keep all historical content forever. Fossil |
|
6
|
purposely makes it difficult for users to delete content. Old content |
|
7
|
is part of the project's <i>*ahem*</i> fossil record and should be |
|
8
|
maintained indefinitely to maintain an accurate history of the project. |
|
9
|
|
|
10
|
Nevertheless, there may occasionally arise legitimate reasons for |
|
11
|
deleting content. Such reasons include: |
|
12
|
|
|
13
|
* Spammers inserted inappropriate content into a wiki page, forum post, |
|
14
|
or ticket. Fossil lets you easily hide or amend such content, but |
|
15
|
since it is not a legitimate part of the project's history, there |
|
16
|
is no value in keeping it, so it is best removed permanently. |
|
17
|
|
|
18
|
* A file that contains trade secrets or that is under someone else's |
|
19
|
copyright was accidentally committed and needs to be backed out. |
|
20
|
|
|
21
|
* A malformed control artifact was inserted and is disrupting the |
|
22
|
operation of Fossil. |
|
23
|
|
|
24
|
* A legitimate legal request was received requiring content to |
|
25
|
be removed. This would most likely be related to the accidental |
|
26
|
intellectual property error or spam cases listed above. Some countries |
|
27
|
recognise software patents, and so allow legal claims targetting code |
|
28
|
commits. Some countries can require publicly-available encryption |
|
29
|
software to be taken down if it is committed to the DAG without |
|
30
|
the correct government authorisation. |
|
31
|
|
|
32
|
<h2>Alternatives</h2> |
|
33
|
|
|
34
|
All of these are rare cases: Fossil is [./antibot.wiki | designed to |
|
35
|
foil spammers up front], legally problematic check-ins should range from |
|
36
|
rare to nonexistent, and you have to go way out of your way to force |
|
37
|
Fossil to insert bad control artifacts. Therefore, before we get to |
|
38
|
methods of permanently deleting content from a Fossil repo, let's give |
|
39
|
some alternatives that usually suffice, which don't damage the project's |
|
40
|
fossil record: |
|
41
|
|
|
42
|
* When a forum post or wiki article is "deleted," what actually |
|
43
|
happens is that a new empty version is added to the Fossil repository. |
|
44
|
The web interface interprets this |
|
45
|
as "deleted," but the prior version remains available if you go |
|
46
|
digging for it. |
|
47
|
|
|
48
|
* When you close a ticket, it's marked in a way that causes it |
|
49
|
to not show up in the normal ticket reports. You usually want to |
|
50
|
give it a Resolution such as "Rejected" when this happens, plus |
|
51
|
possibly a comment explaining why you're closing it. This is all new |
|
52
|
information added to the ticket, not deletion. |
|
53
|
|
|
54
|
* When you <tt>fossil rm</tt> a file, a new manifest is |
|
55
|
checked into the repository with the same file list as for the prior |
|
56
|
version minus the "removed" file. The file is still present in the |
|
57
|
repository; it just isn't part of that version forward on that |
|
58
|
branch. |
|
59
|
|
|
60
|
* If you make a bad check-in, you can shunt it off to the side |
|
61
|
by amending it to put it on a different branch, then continuing |
|
62
|
development on the prior branch: |
|
63
|
<br><br> |
|
64
|
<code>$ fossil amend abcd1234 --branch BOGUS --hide<br> |
|
65
|
$ fossil up trunk</code> |
|
66
|
<br><br> |
|
67
|
The first command moves check-in ID <tt>abcd1234</tt> (and any |
|
68
|
subsequent check-ins on that branch!) to a branch called |
|
69
|
<tt>BOGUS</tt>, then hides it so it doesn't show up on the |
|
70
|
timeline. You can call this branch anything you like, and you can |
|
71
|
re-use the same name as many times as you like. No content is |
|
72
|
actually deleted: it's just shunted off to the side and hidden away. |
|
73
|
You might find it easier to do this from the Fossil web UI in |
|
74
|
the "edit" function for a check-in. |
|
75
|
<br><br> |
|
76
|
The second command returns to the last good check-in on that branch |
|
77
|
so you can continue work from that point. |
|
78
|
|
|
79
|
* When the check-in you want to remove is followed by good |
|
80
|
check-ins on the same branch, you can't use the previous method, |
|
81
|
because it will move the good check-ins, too. The solution is: |
|
82
|
<br><br> |
|
83
|
<tt>$ fossil merge --backout abcd1234</tt> |
|
84
|
<br><br> |
|
85
|
That creates a diff in the check-out directory that backs out the |
|
86
|
bad check-in <tt>abcd1234</tt>. You then fix up any merge conflicts, |
|
87
|
build, test, etc., then check the reverting change into the |
|
88
|
repository. Again, nothing is actually deleted; you're just adding |
|
89
|
more information to the repository which corrects a prior |
|
90
|
check-in. |
|
91
|
|
|
92
|
<h2>Exception: Non-versioned Content</h2> |
|
93
|
|
|
94
|
It is normal and expected to delete data which is not versioned, such as |
|
95
|
usernames and passwords in the user table. The [/help/scrub|fossil scrub] |
|
96
|
command will remove all sensitive non-versioned data from a repository. |
|
97
|
|
|
98
|
The scrub command will remove user 'bertina', along with their password, |
|
99
|
any supplied IP address, any concealed email address etc. However, in the |
|
100
|
DAG, commits by 'bertina' will continue to be visible unchanged even though |
|
101
|
there is no longer any such user in Fossil. |
|
102
|
|
|
103
|
<h2>Shunning</h2> |
|
104
|
|
|
105
|
Fossil provides a mechanism called "shunning" for removing content from |
|
106
|
a repository. |
|
107
|
|
|
108
|
Every Fossil repository maintains a list of the hash names of |
|
109
|
"shunned" artifacts. |
|
110
|
Fossil will refuse to push or pull any shunned artifact. |
|
111
|
Furthermore, all shunned artifacts (but not the shunning list |
|
112
|
itself) are removed from the |
|
113
|
repository whenever the repository is reconstructed using the |
|
114
|
"rebuild" command. |
|
115
|
|
|
116
|
<h3>Shunning lists are local state</h3> |
|
117
|
|
|
118
|
The shunning list is part of the local state of a Fossil repository. |
|
119
|
In other words, shunning does not propagate to a remote repository |
|
120
|
using the normal "sync" mechanism. An artifact can be |
|
121
|
shunned from one repository but be allowed to exist in another. The fact that |
|
122
|
the shunning list does not propagate is a security feature. If the |
|
123
|
shunning list propagated then a malicious user (or |
|
124
|
a bug in the fossil code) might introduce a shun record that would |
|
125
|
propagate through all repositories in a network and permanently |
|
126
|
destroy vital information. By refusing to propagate the shunning list, |
|
127
|
Fossil ensures that no remote user will ever be able to remove |
|
128
|
information from your personal repositories without your permission. |
|
129
|
|
|
130
|
The shunning list does not propagate to a remote repository |
|
131
|
by the normal "sync" mechanism, |
|
132
|
but it is still possible to copy shuns from one repository to another |
|
133
|
using the "configuration" command: |
|
134
|
|
|
135
|
<b>fossil configuration pull shun</b> <i>remote-url</i><br> |
|
136
|
<b>fossil configuration push shun</b> <i>remote-url</i> |
|
137
|
|
|
138
|
The two commands above will pull or push shunning lists from or to |
|
139
|
the <i>remote-url</i> indicated and merge the lists on the receiving |
|
140
|
end. "Admin" privilege on the remote server is required in order to |
|
141
|
push a shun list. In contrast, the shunning list will be automatically |
|
142
|
received by default as part of a normal client "pull" operation unless |
|
143
|
disabled by the "<tt>auto-shun</tt>" setting. |
|
144
|
|
|
145
|
Note that the shunning list remains in the repository even after the |
|
146
|
shunned artifact has been removed. This is to prevent the artifact |
|
147
|
from being reintroduced into the repository the next time it syncs with |
|
148
|
another repository that has not shunned the artifact. |
|
149
|
|
|
150
|
<h3>Managing the shunning list</h3> |
|
151
|
|
|
152
|
The complete shunning list for a repository can be viewed by a user |
|
153
|
with "admin" privilege on the "/shun" URL of the web interface to Fossil. |
|
154
|
That URL is accessible under the "Admin" button on the default menu |
|
155
|
bar. Items can be added to or removed from the shunning list. "Sync" |
|
156
|
operations are inhibited as soon as the artifact is added to the |
|
157
|
shunning list, but the content of the artifact is not actually removed |
|
158
|
from the repository until the next time the repository is rebuilt. |
|
159
|
|
|
160
|
When viewing individual artifacts with the web interface, "admin" |
|
161
|
users will usually see a "Shun" option in the submenu that will take |
|
162
|
them directly to the shunning page and enable that artifact to be |
|
163
|
shunned with a single additional mouse click. |
|
164
|
|