Приводим в порядок свой open source репозиторий: приемы командной строки

0
635
views

Перевод статьи «Command line tricks for managing your messy open source repository».

Эффективное сотрудничество, особенно в разработке программного обеспечения, начинается с эффективной организации. Чтобы ничего не пропустить, следует руководствоваться правилом «одна проблема — один пул-реквест».

Если в проекте с открытым кодом будут не объемные issue вроде «Исправить битые ссылки в документации», а более мелкие и доступные (пускай даже их будет больше), такой проект скорее привлечет контрибьюторов. Если брать пример с битыми ссылками, можно разделить задачу на несколько частей, чтобы люди могли заняться исправлением ссылок в отдельном разделе или на отдельной странице. Это позволит контрибьюторам быстро присоединиться к проекту, уделив ему немного своего свободного времени, а вам не придется ждать, пока кто-то решиться взять на себя большую задачу.

Более мелкие issues также помогают мейнтейнерам проекта следить за тем, где работы закончены, а где — еще нет. Это снижает вероятность того, что какая-то часть проблемы будет пропущена, хотя все будут думать, что этот вопрос давно решен. Подобное может привести к багам и уязвимостям в безопасности.

Это все хорошо, но если вы уже открыли несколько массивных issues, вероятно, какие-то пул-реквесты уже были одобрены или даже слиты, и в настоящее время вы понятия не имеете, на каком этапе находится работа в целом.

Чтобы вернуть себе контроль над состоянием проекта, нужно его упорядочить. Хорошо, что у нас есть достаточное количество инструментов командной строки, способных помочь нам проверить, отсортировать и упорядочить репозиторий. Вот небольшое число инструментов, которыми я сама пользуюсь.

Интерактивный поиск и замена при помощи Vim

Вы можете открыть файл в Vim, а затем осуществить интерактивный поиск с заменой:

:%s/\<word\>/newword/gc

Знак % указывает редактору, что искать нужно во всех строках текущего файла; s означает замену; \<word\> — целое слово; g означает «global», т. е., замена для всех вхождений, а не для первого, которое найдется. Буква «c» в конце позволит вам просматривать и подтверждать каждое изменение. Можно запустить и автоматическую замену (не добавляя «с»), так процесс пойдет быстрее, но если вы где-то допустили ошибку в шаблоне поиска, это может привести к нежелательным последствиям.

Поиск битых ссылок в Markdown-файлах при помощи node-модуля

У node-модуля markdown-link-check есть отличный CLI-напарник.

Я так часто им пользуюсь, что даже превратила в Bash-функцию. Чтобы сделать так же, добавьте в свой файл .bashrc следующие строки:

Markdown link check in a folder, recursive
 function mlc () {
     find $1 -name *.md -exec markdown-link-check -p {} \;
 }

После этого можно будет запускать функцию, введя

mlc <filename>

Вывести список поддиректорий с git-репозиториями (или без оных) при помощи команды find

Предположим, вам нужно вывести на экран все субдиректории, являющиеся репозиториями git, т. е., содержащие .git. Вам поможет следующая команда:

find . -maxdepth 1 -type d -exec test -e '{}/.git' ';' -printf "is git repo: %p\n"

Чтобы вывести все субдиректории, не являющиеся репозиториями git, следует инвертировать test при помощи восклицательного знака:

find . -maxdepth 1 -type d -exec test '!' -e '{}/.git' ';' -printf "not git repo: %p\n"

Вытащить несколько git-репозиториев из списка при помощи xargs

Изначально я пользовалась этим приемом для автоматического восстановления моего ноутбука при помощи Bash-скриптов, но он довольно удобен и для работы с облачными вещами или файлами Docker.

Имея файл repos.txt, с SSH-ссылкой репозитория на каждой строке (и вашими SSH-ключами), запустите:

xargs -n1 git clone < repos.txt

Об извлечении и отправке большого количества репозиториев я уже писала в статье, где разбиралось использование Bash для управления репозиториями.

Вывести список issues по номерам при помощи jot

Я соавтор и мейнтейнер репозитория OWASP Web Security Testing Guide. Там я недавно взяла одну объемную задачу (да, это было «Исправить все битые ссылки в документации». И как вы только догадались?) и разделила ее на несколько задач поменьше. То есть, на 37 более удобоваримых задач.

Я хотела пронумеровать все issues, получившиеся из одной задачи, но идея вводить вручную 37 номеров (от #275 до #312) показалась мне слишком нудной и затратной по времени. Поэтому я использовала время, которое потратила бы на нумерацию, для изобретения способа автоматизировать этот процесс. Настоящий программистский подход!

Утилита jot (apt install athena-jot) это маленький инструмент, очень полезный в деле вывода чисел. Просто укажите ему, сколько чисел вам нужно, а также с чего начать и где остановиться.

jot [ reps [ begin [ end ] ] ]
jot 37 275 312

Эта команда выведет на новой строке все числа, от 275 по 312 включительно. Чтобы превратить эти числа в номера issue в нотации, автоматически распознаваемой GitHub и многими другими платформами, а также сделать их ссылками, вы можете перенаправить вывод команды в awk:

jot 37 275 312 | awk '{printf "#"$0", "}'
#275, #276, #277, #278, #279, #280, #281, #282, #283, #284, #285, #286, #287, #288, #289, #290, #291, #292, #293, #295,

Также можно использовать jot для генерации рандомных данных. Это может пригодиться в разработке программ или в тестировании.

Хорошо организованный open source репозиторий это хорошо поддерживаемый open source проект. Сохраните себе этот пост в качестве справочника и используйте новые знания CLI во благо!