Lesson 4 · 17 min
Adding a link back in forty repositories, swapping a footer on a hundred pages, fixing a canonical across the whole site: this is where the agent saves you hours, and this is where one mistake spreads. Three protections solve almost everything: show before you do, don't duplicate, and don't touch what someone else is working on.
Start the lesson
Goal: run an operation across several repositories with a dry-run, a marker against duplicating, and skipping dirty repos, checking by sample.
Tap each block.
Three protections: dry-run, marker, and skipping a dirty repository.
Tap each step.
The script's default is not to write. Writing requires asking for it: --apply. That way a mistake in the map shows up in the list, not on the site.
Ask any agent for the same thing: first the list of what it would do, then the run.
The written block goes between two comments with the marker link-de-volta:v1. Before writing, the script looks for the marker: if it's already there, it answers "OK: já tinha".
This is what lets you run it again after a failure without creating two links on the same page.
If the repository has an uncommitted change, the script skips it. It's almost always another session (yours or another agent's) working on it.
It also skips a repository that's not on the expected branch and one that has no HTML. In INEMA, repositories skipped because of a dirty working tree were left for the next round.
If index.html is just a redirect (meta refresh), the link goes on the destination page. If the HTML is generated by a script, the link goes in the generator, otherwise it disappears on the next build.
In INEMA: 35 of 40 repositories on 09/24, another 25 on 10/02, and another 21 on 10/05.
Swap the paths and destinations for your own.
[{"repo": "repos/curso-pao", "destino": "https://www.seusite.com/cursos/pao/", "rotulo": "Ficha completa"},
{"repo": "repos/curso-cafe", "destino": "https://www.seusite.com/cursos/cafe/", "rotulo": "Ficha completa"},
{"repo": "repos/curso-queijo", "destino": "https://www.seusite.com/cursos/queijo/", "rotulo": "Ficha completa"},
{"repo": "repos/curso-vinho", "destino": "https://www.seusite.com/cursos/vinho/", "rotulo": "Ficha completa"}]python3 tools/link_de_volta.py mapa.json # dry-run: só mostra python3 tools/link_de_volta.py mapa.json --apply # grava, sem commit python3 tools/link_de_volta.py mapa.json --apply --commit # grava, commita e faz push
Build the mapa.json with the repositories from the list and run link_de_volta.py with NO options (dry-run). Show me the full output and stop. Don't use --apply or --commit until I reply "aplica". Repository with PULA: don't force it, don't stash, don't commit for it. Just tell me which one it is.
$ python3 tools/link_de_volta.py mapa.json repos/curso-pao: DRY: entraria em index.html repos/curso-cafe: PULA: alterações não commitadas repos/curso-queijo: OK: já tinha repos/curso-vinho: DRY: entraria em landing.html $ python3 tools/link_de_volta.py mapa.json --apply repos/curso-pao: APLICADO em index.html repos/curso-cafe: PULA: alterações não commitadas repos/curso-queijo: OK: já tinha repos/curso-vinho: APLICADO em landing.html
Four test repositories set up for the lesson.
After --apply without --commit, curso-pao and curso-vinho are left with an uncommitted change: running again without committing makes the script skip both. Commit or discard before the next round.
Run it, interrupt halfway, and run it again. What's already done isn't redone.
Illustrative simulation in the browser: nothing is actually written. The skip is on purpose, to show the dirty repository.
Use 3 or more of your own repositories (or create test repositories with a simple index.html).
Ask the agent for the mapa.json and the dry-run, using the request above. Leave one repository with an uncommitted change on purpose.
Done when: the output shows at least one DRY and one PULA with the reason, and the git status of the repositories did not change.
Reply "aplica", run with --apply, check the diff of each repository, commit (or use --commit), and run the dry-run again.
Done when: the second run answers "OK: já tinha" in the repositories you applied, and you opened at least 2 published pages and saw the link in the HTML.
The explanation appears after your answer.
Question 1 of 4
What does link_de_volta.py do when you run it with no options?skill
Question 2 of 4
A repository shows up as "PULA: alterações não commitadas". What should you do?
Question 3 of 4
What is the link-de-volta:v1 marker for?
Question 4 of 4
A course's index.html is just a redirect. Where should the link go?
Choose an option. The explanation appears after your attempt.