|author||Amin Bandali <firstname.lastname@example.org>||2020-07-26 17:06:25 -0400|
|committer||Amin Bandali <email@example.com>||2020-07-26 17:06:25 -0400|
edit: improve the instructions
Diffstat (limited to 'edit.md')
1 files changed, 87 insertions, 19 deletions
@@ -26,9 +26,9 @@ commits with hashes of the commits of a clone over the insecure
We strongly recommend using `ssh://` (which is both secure and allows
pushes), and avoiding `git://` (no transport security) and `https://`
+(read-only access) when possible.
-## SSH access (recommended method)
+## 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
@@ -65,7 +65,7 @@ something along these lines in your terminal:
chmod 600 ~/.ssh/id_rsa_anon_git_emacsconf
You can show the fingerprint of the key to examine with the expected
-fingerprint mentioned ealier using:
+fingerprint mentioned earlier using:
ssh-keygen -lf ~/.ssh/id_rsa_anon_git_emacsconf
@@ -86,27 +86,95 @@ wiki sources. To do so, run:
git clone firstname.lastname@example.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
+for more details and instructions).
-Now, go ahead and make your changes to the website sources in the
-repository you just cloned. When you're done, do:
+## Pulling in changes by others
- git add X Y Z
- git commit -m"descriptive commit message"
+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
+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`.
-where `X`, `Y`, and `Z` are the files you changed; and `descriptive
-commit message` is, well, a descriptive text describing your
+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.
-When you are ready, 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
+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"
-If you have any questions, or still cannot push to the wiki having
-followed the above instructions, don't hesitate to get in touch with
+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
+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
+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`).
+## 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]].