diff options
| -rw-r--r-- | edit.md | 106 |
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). +(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 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)). +Setup](//git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup) +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 +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`. -where `X`, `Y`, and `Z` are the files you changed; and `descriptive -commit message` is, well, a descriptive text describing your -changes. :-) +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 -seconds. +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 -[[bandali]]. +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`). + +## 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]]. |