1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
[[!meta title="Editing the EmacsConf wiki"]]
[[!meta copyright="Copyright © 2020 Amin Bandali"]]
This site is a wiki, editable by anyone on the planet. The pages are
written in markdown, and converted to HTML using the
[ikiwiki](//ikiwiki.info) wiki compiler. You are welcome and
encouraged to edit and help improve the site.
**Important:** see the [[EmacsConf wiki license terms|COPYING]] 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`](/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](//git-scm.com/book/en/v2/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]].
|
