====== Github setup ======
Github (source forge) is not git (local-first distributed source control management software)! See [[:tools:git]] for using ''git''.


Github setup includes
  - [[#new_repo|creating]] or [[#existing_repo|finding]] an existing remote github repository url
    * avoid conflicting histories: <wrap important>dont generate a readme when creating a new repo</wrap> 
  - syncing that with your files (on your computer, on rhea, on PSC, etc)
    * <wrap tip> be sure you ''cd'' to the right directory before running ''git'' commands</wrap>
  - [[#ssh_keys|authenticating]] with github for ''git push'' permissions. 
    * <wrap tip>ssh keys recommended</wrap>
    * <wrap alert> ''ssh-keygen'' only once per user@server. don't run if existing ''~/.ssh/id*.pub''</wrap>

===== New Repo =====

<WRAP alert>
If you have an existing directory you want to put on github, **DO NOT** generate a readme when creating the  github repository.
</WRAP>
 
  *  {{.:pasted:20251016-101712.png?100}} http://github.com/new or Home > green new repo
  * {{.:pasted:20251016-101911.png?100}} Follow form to assign a name.  <wrap important>only add readme, lic, etc if no project files exist locally yet</wrap> 
  * {{.:pasted:20251016-102226.png?200}} Follow the instructions github provides <wrap tip>be sure to ''cd'' into the code directory before running ''git'' commands</wrap>  <code bash add_remote.bash>
cd my-exsiting-data/ # go to the directory of your existing code
git remote add origin git@github.com:$USER/$REPONAME
git push -u origin main</code>

===== Existing Repo =====

  * Copy the ssh url of your new repository. Green ''<> Code'' button > ''Local'' Tab > ''SSH'' header.
{{:tools:pasted:20251016-101450.png?200|}}
  * Clone the copied url like <code bash>git clone git@github.com/$USER/$REPO</code>
===== Authentication =====
For ''git push'' to  github, you'll need some way to confirm your credentials. Authentication can happen with <wrap tip>**ssh keys** (recommended)</wrap> or an **app password**
==== ssh keys ====

''git push'' can use ssh authentication unique to a user and computer pair. You need a key likely in ''~/.ssh/id_ed25519.pub''.


Contents of ''~/.ssh/id_ed25519.pub'' should be pasted into ''new ssh key'' modal on https://github.com/settings/keys ((''top right user icon''->''settings''->''ssh and GPG keys'' -> ''new ssh key''))
<code bash>
cat ~/.ssh/id_ed25519.pub
</code>


{{:tools:pasted:20231024-130110.png?300}}


If ''~/.ssh/id_ed25519.pub'' doesn't exist, ''ssh-keygen'' can make it (use empty password for convenience. hit enter at password prompt to leave blank). See more [[https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent|documentaiton on github]] 

<WRAP alert>''ssh-keygen'' only needs to be run once per user per computer. Do not rerun if any ''~/.ssh/id*.pub'' file exists -- you risk deleting your key</WRAP>


==== https app pass ====
To push to ''https'' (vs ssh like ''git@'') repos, you'll need to use a personal authentication token when prompted for a password. See [[https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens|github's documentation]]