Using git to manipulate website source code
Git is a version control system that helps to manage having multiple people work on the same material simultaneously. Every user can hold a local copy of a main repository. The local copies can be on the same machine, or across the world. Users can then modify the local copy as they wish and when the modified material is ready, commit the changes and push them back to the main repository.
Git will not let you push a commit directly if the remote repository has
any newer commits (modifications) than your local copy on the same branch.
In such case where conflict takes place, please fetch and update your local
copy first and
rebase your new modifications on top of the latest
commit as needed.
If you need write access to the repository, please request it via the https://salsa.debian.org/webmaster-team/webwml web interface after logging in to Debian's Salsa platform. If you are new to Debian's website development and have no previous experience, please also send a mail to email@example.com with your self introduction. Please write something useful in your introduction, like which language or which part of the website you plan to work on, and who would vouch for you.
First, you need to install git to work with the repository. Next, configure your user and e-mail details on your computer (please refer to general git documentation to learn how to do this). Then, you can clone the repository (in other words, make a local copy of it) in one of two ways.
The recommended way to work on webwml is to first register an account on salsa.debian.org and enable git SSH access by uploading an SSH public key into your salsa account. See the salsa help pages for more details on how to do that. Then you can clone the webwml repository using the following command:
git clone firstname.lastname@example.org:webmaster-team/webwml.git
If you don't have a salsa account, an alternative method is to clone the repository using the HTTPS protocol:
git clone https://salsa.debian.org/webmaster-team/webwml.git
This will give you the same repository copy locally, but you will not be able to directly push changes back directly this way.
Cloning the whole webwml repository will require downloading about 500MB of data, thus it may be difficult for those with slow or unstable Internet connections. You may try shallow cloning with a minimum depth first for a smaller initial download:
git clone email@example.com:webmaster-team/webwml.git --depth 1
After obtaining a usable (shallow) repository, you can deepen the local shallow copy and eventually convert it to a full local repository:
git fetch --deepen=1000 # deepen the repo for another 1000 commits git fetch --unshallow # fetch all missing commits, convert the repo to a complete one
You can create a checkout for only a subset of the pages like this:
$ git clone --no-checkout firstname.lastname@example.org:webmaster-team/webwml.git $ cd webwml $ git config core.sparseCheckout true In webwml: Create the file .git/info/sparse-checkout with content like this (if you only want the base files, English, Catalan and Spanish translations): /* !/[a-z]*/ /english/ /catalan/ /spanish/ Then: $ git checkout --
Every few days (and definitely before starting some editing work!) you should do a
to retrieve any files from the repository which have changed.
Note: git is a distributed (not centralised) version control system. This means that when you commit changes they will only be stored in your local repository. To share them with others, you will also need to push your changes to the central repository on salsa.
So editing an English file will work like this:
$ git pull
Now make changes to files. When you are done, commit your changes to your local repository using:
$ git add path/to/file(s) $ git commit -m "Your commit message"
Then, push your changes to the Salsa repo:
$ git push
That's a very basic summary of how to use git to manipulate the Debian website's source code. For more information on git, please read git's documentation.
If you include
Closes: #nnnnnn in your commit log
entry, then bug number
#nnnnnn will be closed
automatically when you push your changes. The precise form of this is the same as
in Debian policy.
Many Debian websites support SSL, so please use HTTPS links where possible and sensible. However, some Debian/DebConf/SPI/etc websites either don't have have HTTPS support or only use the SPI CA (and not an SSL CA trusted by all browsers). To avoid causing error messages for non-Debian users, please do not link to such sites using HTTPS.
The git repository will reject commits containing plain HTTP links for Debian websites that support HTTPS or containing HTTPS links for the Debian/DebConf/SPI websites that are known to either not support HTTPS or use certificates signed only by SPI.
If you change translated files, you need to update the translation-check header to match the git commit hash of the corresponding change in the English file. You can find that hash with
$ git log path/to/english/file
If you do a new translation of a file, please use the
and it will create a template for your language, including the correct
smart_change.pl is a script designed to make it easier
to update original files and their translations together. There are
two ways to use it, depending on what changes you are making.
smart_change to just update the translation-check
headers when you're working on files manually:
- Make the changes to the original file(s), and commit
- Update translations
- Run smart_change.pl - it will pick up the changes and update headers in the translated files
- Review the changes (e.g. with "git diff")
- Commit the translation changes
Or, if you're using smart_change with a regular expression to make multiple changes across files in one pass:
smart_change.pl -s s/FOO/BAR/ origfile1 origfile2 ...
- Review the changes (e.g. with
- Commit the original file(s)
smart_change.pl origfile1 origfile2(i.e. without the regexp this time);it will now just update headers in the translated files
- Finally, commit the translation changes
This is more involved than previously (needing two commits), but unavoidable due to the way git commit hashes work
We have configured the webwml project in Salsa so that commits are shown in the IRC channel #debian-www.
If you want to receive notifications via e-mail when there are
commits in the webwml repo, please subscribe to the
pseudopackage via tracker.debian.org and activate the
there, following these steps (only once):
- Open a web browser and go to https://tracker.debian.org/pkg/www.debian.org
- Subscribe to the
www.debian.orgpseudopackage. (You can authenticate via SSO or register an email and password, if you were not using tracker.debian.org already for other purposes).
- Go to https://tracker.debian.org/accounts/subscriptions, then to
modify keywords, check
vcs(if it's not checked) and save.
- From now on you will get e-mails when somebody commits to the webwml repo. We will add the other webmaster-team repositories soon.