You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A plugin for RepoBee to sanitize template repositories before being pushed to
11
-
students. `repobee-sanitizer` adds the commands `sanitize-file` and
12
-
`sanitize-repo` that lets the user sanitize files and repos (directories
13
-
currently) respectively. `repobee-sanitizer` can remove or replace text by
14
-
going through files, looking for certain `REPOBEE-SANITIZER-<type>`
15
-
text-markers. The most simple usage consists of a `REPOBEE-SANITIZER-START` and
16
-
a `REPOBEE-SANITIZER-END` marker, where content between these two markers will
17
-
be removed, or "sanitized" as it were.
18
-
19
-
## Install
20
-
Use RepoBee's plugin manager to install and activate.
10
+
# Overview
21
11
22
-
```
23
-
$ repobee plugin install
24
-
$ repobee plugin activate # persistent activation
25
-
```
12
+
## Problem
26
13
27
-
`repobee-sanitizer` only adds new commands, so we recommend [activating it persistently](https://repobee.readthedocs.io/en/latest/plugins.html#persistent-plugin-activation-and-deactivation) after installing. For general instructions on installing and using plugins, see [RepoBee's plugin docs](https://repobee.readthedocs.io/en/latest/plugins.html).
14
+
When working with version control systems to maintain code, it is possible to want different versions of a file or even a whole repository. An example of this would be a teacher using GitHub to manage separate template repositories (repo) for code assignments, solutions, and unit tests.
28
15
29
-
## Commands
30
-
`repobee-sanitizer` supports two main commands: `sanitize file` and `sanitize repo`
16
+
Managing solutions and assignments separately becomes an issue when updates are made. If the assignment is updated, the solution and tests also have to be updated, and the teacher has to ensure that all repos are compatible, we call this drift. Working with separate repos simultaneously can be a pain as the teacher has to jump around and make changes in different places, essentially cluttering one's workplace.
31
17
32
-
### The `sanitize file` command
18
+
##Solution
33
19
34
-
`repobee sanitize file <infile> <outfile>` performs the sanitization operation described below directly on a file `infile` and writes the output to `outfile`.
20
+
To combat the issues mentioned above, we have developed `Sanitizer`, a plug-in for RepoBee that
21
+
allows the user to manage their assignments and solutions inside a single repository.
35
22
36
-
Running the following command will sanitize `input.txt` (given that it exists) and create the file `sanitized.txt` containing, you guessed it, the sanitized file. `sanitized.txt` will be overwritten if it already exists.
23
+
`Sanitizer` adds the commands `sanitize file` and `sanitize repo` that lets the user sanitize
24
+
files and git repositories. `Sanitizer` works by removing or replacing text by going through
25
+
files as text, looking for a certain markup described below. The most simple usage
26
+
consists of a start and end marker, where content between these two markers will be
27
+
removed, or "sanitized" as it were.
37
28
38
-
```
39
-
$ repobee sanitize file input.txt sanitized.txt
40
-
```
29
+
This solution allows teachers to safely work inside a single repository, without the chance of solutions reaching students when creating student repositories (human error not accounted for).
30
+
The problem of drift is also removed, and as a bonus, teachers can easily create their assignments
31
+
using solution driven development.
41
32
42
-
The `--strip` flag can also be used to reverse the operation, instead removing all sanitizer syntax from the file.
33
+
# Usage
43
34
44
-
### The `sanitize repo` command
35
+
## Install
36
+
Use `RepoBee`'s plugin manager to install and activate.
45
37
46
-
`sanitize repo` performs the sanitization protocol on an entire repository. It's most basic usage looks like so:
47
38
```
48
-
$ repobee sanitize repo --no-commit
39
+
$ repobee plugin install
40
+
$ repobee plugin activate # persistent activation
49
41
```
50
-
Assuming that you're currently at the root of a Git repository, this will sanitize the current branch without making a commit.
51
42
52
-
#### Repo root
53
-
If you are not currently at the root of a repository, a path can be specified using the `--repo-root <path>` option.
43
+
`Sanitizer` only adds new commands, so we recommend [activating it persistently](https://repobee.readthedocs.io/en/latest/plugins.html#persistent-plugin-activation-and-deactivation) after installing. For general instructions on installing and using plugins, see [RepoBee's plugin docs](https://repobee.readthedocs.io/en/latest/plugins.html).
54
44
55
-
#### Branches
56
-
Another important feature is working with branches, `repobee-sanitizer` was essentially made to manage differing branches. For an example, a repo can have a `solutions` and a `main` branch, where the `solutions` branch contains an entire solution to an assignment, as well as `sanitizer``markers` (specified below). When we then sanitize the `solutions` branch, we create a slimmed-down version of our repo (that we would send to students), what we can then do is to specify which branch we want the sanitied version to end up on.
57
-
58
-
This is done using the `--target-branch <branch-name>` option. For example, if our repo is checked out to the branch `solutions` (that contains full solutions and `sanitizer``markers`), Running:
59
-
60
-
` $ repobee sanitize repo --target-branch main`
45
+
## Syntax
61
46
62
-
will sanitize the currently checked out branch (in this case `solutions`) and commit the result to the specified branch, in this case `main`. Successfully using the `--target-branch` feature allows us to essentially retain two concurrent repositories while only having to update one of them should any changes or improvements be made to our course tasks.
47
+
For `Sanitizer` to work, marker syntax must be correct, this includes
48
+
spelling of the markers themselves, the markers currently are as follows:
63
49
64
-
#### Errors / Force
65
-
`repobee-sanitizer` does its best to ensure that nothing breaks while sanitizing. Therefore, when sanitizing a repo, `repobee-sanitizer` will always make sure you have no uncommited files in the repo as well as no syntax errors (in you `sanitizer` syntax). If you do have an error, sanitizer will _not_ sanitize _anything_ untill you fix any errors and run the command again. `repobee-sanitizer` even prevents you from commiting if no changes will be made to the repo!
50
+
- REPOBEE-SANITIZER-START
51
+
- REQUIRED: A block is not a block without a start marker
52
+
- Indicates the start of a block. Any text will be removed until reaching
53
+
a `REPLACE-WITH` or `END` marker.
54
+
- REPOBEE-SANITIZER-REPLACE-WITH
55
+
- OPTIONAL: but requires a start and end block.
56
+
- Any text between this marker and the next `END` marker will remain.
57
+
- REPOBEE-SANITIZER-END
58
+
- REQUIRED: Must exist for each start block
59
+
- Indicates the end of a block.
60
+
- REPOBEE-SANITIZER-SHRED
61
+
- OPTIONAL: Can only exist on the first line of a file. If this exists,
62
+
there cannot be any other markers of any type in the file
63
+
- Having this marker will remove the entire file when running the
64
+
`sanitize-repo` or `sanitize-file` commands
66
65
67
-
If you are completely and utterly sure that computers are stupid things and that you are a far superior being, you may use the `--force` flag to ignore any warnings related uncommited files/changes in the repo (Jokes aside this is necessary sometimes, like if you want to commit when no changes were made).
66
+
If a marker is incorrectly spelled, `repobee-sanitizer` will report an error.
68
67
69
68
## Example use cases
70
69
@@ -93,10 +92,10 @@ REPOBEE-SANITIZER-END
93
92
}
94
93
```
95
94
96
-
>Example 1: The simplest usage of `repobee-sanitizer` using a .java file
95
+
>Example 1: The simplest usage of `Sanitizer` using a .java file
97
96
98
97
For this .java test file, the `santize-file` command will identify the START
99
-
and END markers, and proceed to remove the code inbetween. The result will look
98
+
and END markers, and proceed to remove the code between the markers. The result will look
100
99
like this:
101
100
102
101
```java
@@ -107,7 +106,7 @@ class StackTest {
107
106
}
108
107
```
109
108
110
-
`repobee-sanitizer` also supports the `REPOBEE-SANITIZER-REPLACE-WITH` marker.
109
+
`Sanitizer` also supports the `REPOBEE-SANITIZER-REPLACE-WITH` marker.
111
110
By adding a replace marker, we can specify code that should replace the removed
112
111
code. Example as follows:
113
112
@@ -143,8 +142,8 @@ As we can see in Example 2, this lets us provide two versions of a function,
143
142
one that is current, and one that will replace it. Example 1 and 2 shows us a
144
143
piece of code used in the KTH course DD1338. This code is part of an assignment
145
144
where students are asked to implement a test function. The example shows a
146
-
finished solution that is availiable to the teachers of the course. However,
147
-
because of `repobee-sanitizer` and the `REPLACE-WITH` marker, the code can be
145
+
finished solution that is available to the teachers of the course. However,
146
+
because of `Sanitizer` and the `REPLACE-WITH` marker, the code can be
148
147
reduced to the following:
149
148
150
149
```java
@@ -159,14 +158,14 @@ class StackTest {
159
158
> Example 3: Sanitized code that is provided to students.
160
159
161
160
We can see that the only code that remains inside the function is that of the
162
-
`REPLACE-WITH` marker. This gives us the main usage that `repobee-santizer` was
161
+
`REPLACE-WITH` marker. This gives us the main usage that `Sanitizer` was
163
162
developed for, it allows us to combine finished solutions with the
164
163
"skeletonized" solutions that are provided to students.
165
164
166
165
## Prefixing
167
166
168
167
Sometimes (usually) we want code that can run, its a good thing then that
169
-
`repobee-sanitizer` blocks can be commented out! Example 2 will produce the
168
+
`Sanitizer` blocks can be commented out! Example 2 will produce the
170
169
same output as the following:
171
170
172
171
```java
@@ -194,46 +193,66 @@ class StackTest {
194
193
}
195
194
```
196
195
197
-
> Example 4: Java code with `repobee-sanitizer` related syntax commented out
196
+
> Example 4: Java code with `Sanitizer` related syntax commented out
198
197
199
-
`repobee-sanitizer` automatically detects if there is a prefix in front of any
198
+
`Sanitizer` automatically detects if there is a prefix in front of any
200
199
markers. This way we can have java comments: `//`, python comments: `#` or
201
200
similar preceding our markers. **This means code can still compile!**
202
201
203
-
### Some rules for prefixing:
202
+
There are some rules for prefixing to observe:
204
203
205
-
`repobee-sanitizer`:
204
+
`Sanitizer`:
206
205
207
-
* Determines prefix as any text that comes before `REPOBEE-SANITIZER-START`
206
+
* Determines prefix as any text (including whitespace) that comes before `REPOBEE-SANITIZER-START`
208
207
* Only determines prefix on a block-to-block basis, meaning that the prefix
209
-
selected at a `BLOCK` marker must be used untill and including the next `END`
208
+
selected at a `START` marker must be used until and including the next `END`
210
209
marker
211
-
* This means that all `repobee-sanitizer` blocks can have individuall
210
+
* This means that all `Sanitizer` blocks can have individual
212
211
prefixes
213
-
* Code between replace and end markers **MUST** also be prefixed
212
+
* Code between replace and end markers **MUST** also be prefixed if one is used
213
+
* Prefixes inside `REPLACE-WITH` blocks are removed when sanitizing
214
214
215
-
## Syntax
215
+
## Commands
216
+
`Sanitizer` supports two main commands: `sanitize file` and `sanitize repo`
216
217
217
-
for `repobee-sanitizer` to work, marker syntax must be correct, this includes
218
-
spelling of the markers themselves, the markers currently are as follows:
218
+
### The `sanitize file` command
219
219
220
-
- REPOBEE-SANITIZER-START
221
-
- REQUIRED: A block is not a block without a start marker
222
-
- Indicates the start of a block. Any text will be removed untill reaching
223
-
a `REPLACE-WITH` or `END` marker.
224
-
- REPOBEE-SANITIZER-REPLACE-WITH
225
-
- OPTIONAL: but requires a start and end block.
226
-
- Any text between this marker and the next `END` marker will remain.
227
-
- REPOBEE-SANITIZER-END
228
-
- REQUIRED: Must exist for each start block
229
-
- Indicates the end of a block.
230
-
- REPOBEE-SANITIZER-SHRED
231
-
- OPTIONAL: Can only exist on the first line of a file. If this exists,
232
-
there cannot be any other markers of any type in the file
233
-
- Having this marker will remove the entire file when running the
234
-
`sanitize-repo` or `sanitize-file` commands
220
+
`repobee sanitize file <infile> <outfile>` performs the sanitization operation described below directly on a file `infile` and writes the output to `outfile`.
235
221
236
-
If a marker is incorrectly spelled, `repobee-sanitizer` will report an error.
222
+
Running the following command will sanitize `input.txt` (given that it exists) and create the file `sanitized.txt` containing, you guessed it, the sanitized file. `sanitized.txt` will be overwritten if it already exists.
223
+
224
+
```
225
+
$ repobee sanitize file input.txt sanitized.txt
226
+
```
227
+
228
+
The `--strip` flag can also be used to reverse the operation, instead removing all Sanitizer syntax from the file.
229
+
230
+
### The `sanitize repo` command
231
+
232
+
`sanitize repo` performs the sanitization protocol on an entire repository. It's most basic usage looks like so:
233
+
```
234
+
$ repobee sanitize repo --no-commit
235
+
```
236
+
Assuming that you're currently at the root of a Git repository, this will sanitize the current branch without making a commit.
237
+
238
+
#### Repo root
239
+
If you are not currently at the root of a repository, a path can be specified using the `--repo-root <path>` option.
240
+
241
+
#### Branches
242
+
Another important feature is working with branches, `Sanitizer` was essentially made to manage differing branches. For an example, a repo can have a `solutions` and a `main` branch, where the `solutions` branch contains an entire solution to an assignment, as well as `Sanitizer``markers` (specified below). When we then sanitize the `solutions` branch, we create a slimmed-down version of our repo (that we would send to students), what we can then do is to specify which branch we want the sanitized version to end up on.
243
+
244
+
This is done using the `--target-branch <branch-name>` option. For example, if our repo is checked out to the branch `solutions` (that contains full solutions and `Sanitizer``markers`), Running:
245
+
246
+
```
247
+
$ repobee sanitize repo --target-branch main
248
+
```
249
+
250
+
will sanitize the currently checked out branch (in this case `solutions`) and commit the result to the specified branch, in this case `main`. Successfully using the `--target-branch` feature allows us to essentially retain two concurrent repositories while only having to update one of them should any changes or improvements be made to our course tasks.
251
+
252
+
#### Errors / Force
253
+
`Sanitizer` does its best to ensure that nothing breaks while sanitizing. Therefore, when sanitizing a repo, `Sanitizer` will always make sure you have no uncommitted files in the repo as well as no syntax errors in your `Sanitizer` syntax. If you do have an error, `Sanitizer` will _not_ sanitize _anything_ until you fix any errors and run the command again. `Sanitizer` even prevents you from committing if no changes will be made to the repo!
254
+
255
+
If you are completely and utterly sure that computers are stupid things and that you are a far superior being, you may use the `--force` flag to ignore any warnings related to uncommitted files/changes in the repo (Jokes aside this is necessary sometimes, like if you want to commit when no changes were made).
0 commit comments