This site is a wiki, editable by anyone on the planet. The pages are written in markdown, and converted to HTML using the ikiwiki wiki compiler. You are welcome and encouraged to edit and help improve the site.

Important: see the EmacsConf wiki license terms before proceeding further and making any changes to the wiki.

To edit the wiki, you need to install git if it is not installed on your machine already. After you do the first-time SSH setup below, you can clone the sources from any one of the following addresses:

anon@git.emacsconf.org:pub/emacsconf-wiki
git://git.emacsconf.org/emacsconf-wiki
https://git.emacsconf.org/emacsconf-wiki

Note that the https:// access is read-only and does not allow pushing changes, while the git@ (SSH) and git:// methods allow pushes as well. Even though https:// access is read-only, it can be useful if you would like to manually cross-check and compare the hashes of commits with hashes of the commits of a clone over the insecure git:// protocol.

We strongly recommend using git@git.emacsconf.org (which is both secure and allows pushes), and avoiding git:// (no transport security) and https:// (read-only access) when possible.

First time SSH setup (recommended method)

To use the ssh:// method, you need openssh installed on your machine, which is available on virtually all GNU/Linux distributions and other Unix-like operating systems like the BSDs.

You also need to download the ssh private key id_rsa_anon_git_emacsconf and install it into ~/.ssh/ (the .ssh directory in your home directory). The key fingerprint is SHA256:XbUoLgO2YH9+phNPKvwq8w0Q/8NhaKfS/VE6pDwTPsM anon@git.emacsconf.org, and its randomart image is:

+---[RSA 2048]----+
|              .  |
|             o . |
|    + o   . o .  |
|   . * + o o     |
|    . * S + .    |
|     + &.B.o     |
|    ..+ E=*      |
|    o.ooo@.o     |
|     +o++..      |
+----[SHA256]-----+

Note that openssh requires SSH private keys to be secured with permissions that prevent other users on your machine from reading or modifying them.

To download the key and set appropriate permissions on it, you run something along these lines in your terminal:

wget https://emacsconf.org/id_rsa_anon_git_emacsconf
mkdir -p ~/.ssh/
mv id_rsa_anon_git_emacsconf ~/.ssh/
chmod 600 ~/.ssh/id_rsa_anon_git_emacsconf

You can show the fingerprint of the key to examine with the expected fingerprint mentioned earlier using:

ssh-keygen -lf ~/.ssh/id_rsa_anon_git_emacsconf

Lastly, you need to create a ~/.ssh/config file (if you don't have one already) and add the following to it:

Host git.emacsconf.org
    Port 22
    User anon
    IdentityFile ~/.ssh/id_rsa_anon_git_emacsconf

The Port 22 line is optional, since SSH uses port 22 by default. The SSH server listens on ports 21, 22, 53, 81, 8000, and 8080 for your convenience, if you need it.

You're now all set and ready to clone the repository containing the wiki sources. To do so, run:

git clone anon@git.emacsconf.org:emacsconf-wiki

Now that you have cloned the sources of the wiki to your machine, you can type cd emacsconf-wiki to change directory to the wiki sources, and start making changes.

If this is your first time using Git, please set valid and real user.name and user.email configurations options (see Getting Started - First-Time Git Setup for more details and instructions).

Pulling in changes by others

If you just cloned the emacsconf-wiki repository using git clone moments ago, you can skip this section. I still recommend reading it now though, as it contains important information for your future edits.

Git is a distributed version control system, meant to allow many people to simultaneously work on a repository, and ultimately consolidate their changes together into a canonical copy of the repository. For our purposes, the canonical emacsconf-wiki repository is the one on the git.emacsconf.org server.

It is quite likely that others have made changes to the emacsconf-wiki since the last time you made changes, and making new changes without first consolidating the changes by others is likely to cause headaches for you down the line.

As such, before making new changes to the wiki, it's always a good idea to check for potential changes by others, by fetching the latest state of the canonical repository from the git.emacsconf.org server. You can do so by running git fetch. You can then see a compact list of changes using git log --pretty=short ..origin. You can omit the --pretty=short to get a more details about the changes. To learn more about git log you can read its manual by running man git-log.

To see a diff of the changes, run git diff ..origin.

Having examined the changes, you can now try pulling them into your local repository. In this workflow, you should almost always be able to run git merge --ff to do that. If for some reason there are any merge conflicts, Git will ask you to resolve them. There are a great many articles around the web explaining how to do that.

If you really get stuck and cannot successfully pull in others' changes, the best approach would be to try looking for others running into similar situations online (e.g. on question boards) and learn how to resolve them. If you're short of time, you can also rename your local copy of emacsconf-wiki repository to something else, clone the repository again, and proceed to make new changes.

Editing pages and committing changes

The wiki pages are written in markdown, and you should be able to use any decent text editor to edit them.

Once you're done making changes, do:

git add X Y Z
git commit -m"descriptive commit message"

where X, Y, and Z are the names of the files you changed; and descriptive commit message is, well, a descriptive text describing your changes.

The first command tells git to get ready to record your changes to the said files, and the second command tells git to "commit" (record) your changes now.

After making a commit, you can start making more changes, add and commit them, and so on. These will all be only in your local repository, until you explicitly push them to the canonical repository.

When you are ready to push your changes from your local copy of emacsconf-wiki to the canonical repository on git.emacsconf.org, and assuming you have read and agree with the license terms linked at the top of this page, you can push your changes by running git push. If all goes well, your commit will be pushed, and your changes will appear on the website within a few seconds.

Note that the act of pushing commits using git push is an irreversible step and cannot be undone. The effects of changes, of course, can be reversed by making a series of new changes that reverse the current changes. Git even has a revert subcommand just for that (see man git-revert).

Note to EmacsConf admins

If you need to add or update files that are normally restricted by the pre-receive hook, modify your ~/.ssh/config to specify the User (and optionally IdentityFile) that's registered in the gitolite configuration, and add a remote with git remote add trusted git@git.emacsconf.org:pub/emacsconf-wiki. Then you should be able to push your changes with git push trusted master.

To do this on a temporary basis, override GIT_SSH_COMMAND like so:

GIT_SSH_COMMAND='ssh -i ~/.ssh/id_rsa' git clone git@git.emacsconf.org:pub/emacsconf-wiki

You can confirm your access with ssh git@git.emacsconf.org, which should list the different repositories you have access to.

Have questions?

If you have any questions, or are having trouble pushing your changes to the wiki despite following the above instructions, don't hesitate to get in touch with bandali.