text: # Cache credentials for HTTPS {#credential-caching}
  
  If you plan to push/pull using HTTPS, you want to cache your credentials (username, password), so you don't need to enter them over and over again. Alternatively, you could set up SSH keys (chapter \@ref(ssh-keys)). I suggest you set up one of these methods of authentication on each computer you want to connect to GitHub from.
  
  I find HTTPS easier to get working quickly and **strongly recommend** it when you first start working with Git/GitHub. [It is what GitHub recommends](https://stackoverflow.com/a/11041782/2825349), presumably for exactly the same reasons. I started with HTTPS, but eventually switched over to SSH. Either is fine, and you can change your mind later.
  
  ## You might not need to do anything!
  
  As of January 2019, if you install Git using the [methods recommended here in Happy Git](#install-git), it is possible that Git will use a credential helper provided by your operating system. That is, you may not need to do anything special in order to cache your GitHub username and password.
  
  Specifically, if you are on macOS or Windows, don't do anything described here until you have actual proof that it's necessary, i.e. that you have experienced repeated challenges for your username and password when using HTTPS.
  
  ### Windows
  
  In my most recent experiments, Git for Windows is configured to store credentials via the Windows Credentials Manager. This meant that I only needed to enter my GitHub username and password once to get setup for HTTPS.
  
  Here’s a command to reveal the configuration and the output I see in a fresh installation of Git for Windows:
  
  ``` bash
  $ git config --show-origin --get credential.helper
  file:C:/Program Files/Git/mingw64/etc/gitconfig manager
  ```
  
  ### macOS
  
  *I'm not currently in a position to say if credential caching "just works" on macOS in a fresh Git installations. Have you recently experienced this? [Let me know in an issue](https://github.com/jennybc/happy-git-with-r/issues)! If you need to turn it on explicitly, instructions for that are given below.*
  
  ## Special consideration re: two-factor authentication
  
  If you are using [two-factor authentication](https://help.github.com/articles/about-two-factor-authentication/) (a.k.a. "2FA") with GitHub, you will not be able to use your GitHub password via HTTPS. 2FA users should probably be using [SSH](#ssh-keys) anyway, but I digress.
  
  If you really want to use HTTPS, you must enter a [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) in lieu of your password. This is the same type of PAT you could use to access the [GitHub API](https://developer.github.com/v3/) and that many R users define in `.Renviron` as the environment variable `GITHUB_PAT`.
  
  ## Get a test repository
  
  You need a functioning test Git repository. One that exists locally and remotely on GitHub, with the local repo tracking the remote.
  
  If you have just verified that you can interact with GitHub (chapter \@ref(push-pull-github)) from your local computer, that test repo will be perfect.
  
  If you have just verified that you can work with GitHub from RStudio (chapter \@ref(rstudio-git-github)), that test repo will also be perfect.
  
  You may proceed when
  
    * You have a test repo.
    * You know where it lives on your local computer. Example:
      - `/home/jenny/tmp/myrepo`
    * You know where it lives on GitHub. Example:
      - `https://github.com/jennybc/myrepo`
    * You know the GitHub repo is setup as a remote. In a shell (Appendix \@ref(shell)) working directory set to the local Git repo, enter:
    
          git remote -v
          
      Output like this confirms that fetch and push are set to remote URLs that point to your GitHub repo:
      
          origin	https://github.com/jennybc/myrepo (fetch)
          origin	https://github.com/jennybc/myrepo (push)
          
      Now enter:
      
          git branch -vv
          
      Here we confirm that the local `master` branch is tracking your GitHub master branch (`origin/master`). Gibberish? Just check that your output looks similar to mine:
      
          master b8e03e3 [origin/master] line added locally
  
  ## Verify that your Git is new enough to have a credential helper
  
  In a shell (Appendix \@ref(shell)), do:
  
      git --version
  
  and verify your version is 1.7.10 or newer. If not, update Git (chapter \@ref(install-git)) or use SSH keys (chapter \@ref(ssh-keys)).
    
  ## Turn on the credential helper
  
  #### Windows, plan A
  
  The preferred setting for `credential.helper` is now `manager`, which configures Git to use Git Credential Manager for Windows, which ships with Git for Windows. This may already be configured, but this command sets it explicitly:
  
      git config --global credential.helper manager
  
  #### Windows, plan B
  
  If for some reason, Git Credential Manager does not work, you may have success with an older method, `wincred`:
  
      git config --global credential.helper wincred
      
  This is, however, considered deprecated and suggests you should install the current Git for Windows. So only use this as a temporary solution to get unstuck, until you can upgrade.
  
  #### Mac
  
  Find out if the credential helper is already installed. In the shell, enter:
  
      git credential-osxkeychain
      
  And look for this output:
  
      usage: git credential-osxkeychain <get|store|erase>
  
  If you don't get this output, it means you need a more recent version of Git, either via command line developer tools or Homebrew. Go back to the Mac section of chapter (\@ref(install-git)).
  
  Once you've confirmed you have the credential helper, enter:
  
      git config --global credential.helper osxkeychain
  
  #### Linux
  
  In the shell, enter:
  
      git config --global credential.helper 'cache --timeout=10000000'
  
  to store your password for ten million seconds or around 16 weeks, enough for a semester.
  
  ### Trigger a username / password challenge
  
  Change a file in your local repo and commit it. Do that however you wish. Here are shell commands that will work:
  
      echo "adding a line" >> README.md
      git add -A
      git commit -m "A commit from my local computer"
  
  Now push!
  
      git push -u origin master
  
  One last time you will be asked for your username and password, which hopefully will be cached.
  
  Now push AGAIN.
  
      git push
    
  You should NOT be asked for your username and password, instead you should see `Everything up-to-date`.
    
  Rejoice and close the shell.
  