[Docs]: Add some more documentation on how to work with github.

The document roughly describes some workflows, which help new users
to start with github.

docs/github.md

@@ -0,0 +1,130 @@
+# Using Jujutsu with GitHub and GitLab Projects
+
+This guide assumes a basic understanding of either Git or Mercurial. 
+
+## Set up an SSH key
+As of December 2022 it's recommended to set up an SSH key to work with Github
+projects. See [Github's Tutorial][gh]. This restriction may be lifted in the 
+future, see [issue #469][http-auth] for more information and progress on authenticated http. 
+
+
+## Basic workflow
+The simplest way to start with Jujutsu, is creating a stack of commits, before 
+creating any branch. 
+
+```shell script
+# Start a new commit off of `main`
+$ jj new main
+# Refactor some files, then add a description and start a new commit
+$ jj commit -m 'refactor(foo): restructure foo()'
+# Add a feature, then add a description and start a new commit
+$ jj commit -m 'feat(bar): add support for bar'
+# Create a branch so we can push it to GitHub
+$ jj branch create bar -r @-
+# Push the branch to GitHub (pushes only `bar`)
+$ jj git push
+```
+
+While it's possible to create a branch and commit on top of it in a Git like 
+manner, it's not recommended, as no further commits will be placed on the branch. 
+
+## Updating the repository.
+As of December 2022, Jujutsu has no equivalent to a `git pull` command.
+Until such a command is added, you need to use `jj git fetch` followed by a 
+`jj git rebase -d $main_branch` to update your changes. 
+
+## Working in a Git co-located repository
+After doing `jj init --git-repo=.`, git will be in a detached HEAD state,
+which is unusual, as git mainly works with branches. 
+In a co-located repository, `jj` isn't the source of truth. But Jujutsu
+allows a incremental migration, as `jj commit` updates the HEAD of the git
+repository. 
+
+
+Although `jj git import` and `jj git export` exist for co-located repositories,
+they should only be used in case of an unrecoverable error.
+
+```shell script
+$ nvim docs/tutorial.md
+$ # Do some more work.
+$ jj commit -m "Update tutorial"
+$ jj branch create doc-update
+$ # Move the previous revision to doc-update.
+$ jj branch set doc-update -r @- 
+$ jj git push 
+```
+
+## Working in a Jujutsu repository
+In a Jujutsu repository, the workflow is simplified. If there's no need for 
+explicitly named branches, you just can generate one for a change. As Jujutsu 
+is able to create a branch for a revision.
+
+```shell script
+$ # Do your work
+$ jj commit 
+$ # Jujutsu automatically creates a branch
+$ jj git push --change $revision
+```
+
+## Adressing review comments
+There are two workflows for addressing review comments, depending on your 
+project's preference. Many projects prefer that you address comments by adding 
+commits to your branch[^1]. Some projects (such as Jujutsu and LLVM) instead 
+prefer that you keep your commits clean by rewriting them and then force-pushing[^2].
+
+### Adding new commits 
+If your project prefers that you address review comments by adding commmits on 
+top, you can do that by doing something like this:  
+```shell script
+$ # Create a new commit on top of the `your-feature` branch from above.
+$ jj new your-eature
+$ # Adress the comments, by updating the code
+$ jj diff
+$ # Give the fix a description and create a new working-copy on top.
+$ jj commit -m 'address pr comments'
+$ # Update the branch to point to the new commit.
+$ jj branch set your-feature -r @-
+$ # Push it to your remote
+$ jj git push.
+```
+
+### Rewriting commits
+If your project prefers that you keep commits clean, you can do that by doing 
+something like this:  
+```shell script
+$ # Create a new commit on top of the second-to-last commit in `your-feature`,
+$ # as reviews requested a fix there. 
+$ jj new your-feature- 
+$ # Address the comments by updating the code
+$ # Review the changes
+$ jj diff 
+$ # Squash the changes into the parent commit
+$ jj squash
+$ # Push the updated branch to the remote. Jujutsu automatically makes it a force push
+$ jj git push --branch your-feature
+```
+
+## Useful Revsets
+
+Log all revisions across all local branches, which aren't on the main branch 
+nor on any remote    
+`jj log -r 'branches() & ~(main | remote_branches())'`  
+Log all revisions which you authored, across all branches which aren't on any 
+remote  
+`jj log -r 'author([email protected]) & branches() & ~remote_branches()'`  
+Log all remote branches, which you authored or commmited to  
+`jj log -r 'remote_branches() & (comitter([email protected]) | author([email protected]))'`  
+Log all descendants of the current working copy, which aren't on a remote   
+`jj log -r ':@ & ~remote_branches()'`
+
+## Merge conflicts
+
+For a detailed overview, how Jujutsu handles conflicts, revisit the [tutorial][tut].
+
+[^1]: This is a Github Style review, as Github currently is only able to compare branches.
+[^2]: If you're wondering why we prefer clean commits in this project, see e.g.[this blog post][stacked]
+
+[gh]: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent
+[http-auth]: https://github.com/martinvonz/jj/issues/469 
+[tut]: tutorial.md#Conflicts
+[stacked]: https://jg.gg/2018/09/29/stacked-diffs-versus-pull-requests/