This page contains video recordings and written tips for non-engineering teams and how to be Handbook-First. In these videos, we run through the GitLab Handbook with experts, uncovering how to best use the Handbook in our day-to-day work, and learning best-practices for Handbook editing along the way.
Have your own practical Handbook editing tips? Drop a video below!
This video covers:
This video covers:
This video covers:
This video covers:
This video covers:
Some tips may require terminal shell access on macOS/Linux. Ensure that your environment is working and that you have cloned the www-gitlab-com project for example.
git clone https://gitlab.com/gitlab-com/www-gitlab-com.git
Sync it. Ensure that you stash away local changed not yet committed.
cd www-gitlab-com
git stash
git checkout master
git pull
On macOS it is advised to use Homebrew and install the GNU tools. See this blogpost for a macOS setup.
brew install gnu-sed
One of the shell tools provided with macOS/Linux GNU is find. Open a terminal an run the following command in the main directory of the www-gitlab-com repository to get a list of all *.md files. This matches .md as suffix.
find . -type f -name '*.md'
Instead of the . you can also use a directory in the current path.
find source/handbook -type f -name '*.md'
The type f specifies files, d matches for directories. When not specified, all files and directories are taken into account.
You can replace -name with -regex to do more sensitive matching, for example to match all .md and .md.erb files.
find . -type f -regex '.*\.md[.erb]*'
This can be useful to check whether a blog post was merged to master:
git checkout master
git pull
find . -type f -name '*blogpost-filename*'
This comes in handy when you want to print all matches with a prefix, or perform additional replace actions. The main principle is to follow the matching rules explained above, and add the -exec parameter.
The exec action should start a shell and execute a command in there. sh -c '' \; takes care of this for every file that matches. Imagine this as a loop of sequential steps to perform the action. The last missing bit is accessing the file in the current loop iteration. This is done via the {} marker inside the echo example printing the output.
Run the command in a terminal to see how it works:
find source/handbook/marketing -type f -name '*.md' -exec sh -c 'echo "Matched {}"' \;
The GNU sed shell command is useful to replace a defined string in a file. The -i flag specifies to do that inline in the same file. The g flag defines a global match, replacing all pattern matches.
sed -i 's/<searchtext>/<replacementtext>/g' file.md
On macOS, ensure that the gnu-sed package is installed, and run gsed (instead of sed).
gsed -i 's/<searchtext>/<replacementtext>/g' file.md
With using the / separator, it is necessary to escape all / characters in the string. You can avoid this by choosing another separator, for example ,:
gsed -i 's,<searchtext>,<replacementtext>,g' file.md
Sometimes a project, URL target or Slack channel is being renamed. You can easily search and edit with the Web IDE on GitLab.com but for other files there is a quick and automated way required.
This method combines the find, exec and sed tips explained above. The exec action is now to use sed to perform an inline replacement of a pattern/string.
The following example is used in this MR for updating the Corporate Marketing project URL in all files.
git checkout master
git pull origin master
git checkout -b handbook/corp-mktg-project-url
find source/handbook -type f -exec sh -c 'gsed -i "s,https://gitlab.com/gitlab-com/marketing/corporate-marketing,https://gitlab.com/gitlab-com/marketing/corporate_marketing/corporate-marketing,g" "{}"' \;
git status
git diff
git commit -av -m "Handbook: Update corporate marketing project URL"
git push -u origin handbook/corp-mktg-project-url
<open URL in browser for MR>
To cut it down:
source/handbook directory. The URL might be found in other files too.exec runs a sed/gsed actionhttps://gitlab.com/gitlab-com/marketing/corporate-marketing with https://gitlab.com/gitlab-com/marketing/corporate_marketing/corporate-marketinggit status and git diff before committing themsource/handbook/practical-handbook-edits/index.html.md
