Using Sapling with GitHub
When using Sapling with GitHub, we strongly recommend the following:
- Install the GitHub CLI (
gh), as some of our current GitHub integrations rely on it.
- Using the GitHub CLI, authenticate with GitHub via
gh auth login --git-protocol https.
In order for Sapling to work with GitHub pull requests on your behalf, you must provide it with a Personal Access Token (PAT). While the GitHub CLI is not the only way to obtain a PAT, it is certainly one of the most convenient.
While we ultimately plan to remove the requirement of installing the GitHub CLI to use Sapling with GitHub (though the PAT will still be necessary), you will still need some mechanism to cache your GitHub credentials in Git to enjoy the best experience with Sapling. For example, a graphical interface like Interactive Smartlog would be unpleasant to use if it prompted your for a password every time it needed to talk to GitHub. To avoid this, GitHub recommends two solutions for caching your GitHub credentials, the GitHub CLI being the primary choice.
While GitHub gives you the option of cloning a repo with either HTTPS or SSH URLs, HTTPS is generally considered easier to use because HTTPS default port 443 is far less likely to be blocked by a firewall than SSH default port 22.
Cloning a repo
Once you have authenticated via
gh auth login --git-protocol https, you should be able to clone any GitHub repository via its HTTPS URL that you have access to using Sapling:
sl clone https://github.com/facebook/sapling
With the GitHub CLI caching your credentials, you will be able to run commands like
sl ssl to see the status of any linked pull requests in your Smartlog, as it uses your PAT behind the scenes to query their current state.
When it comes to working with pull requests from Sapling, you have three options:
sl ghstack, and
sl push. Each has its tradeoffs, so you may opt to use a different solution, depending on the scenario:
sl pr (aka "Sapling stack")
See the dedicated Sapling Stack page for more information.
- Works with any GitHub repo.
- Creates "overlapping" pull requests that may be confusing to reviewers using the GitHub pull request UI. Reviewers are strongly encouraged to use ReviewStack for code review instead of GitHub.
sl ghstack (aka ghstack for Sapling)
See the dedicated ghstack page for more information.
- Each generated pull request contains one reviewable commit in GitHub.
- Can only be used if you have write access to the repository.
- You will NOT be able to merge these pull requests using the normal GitHub UI.
You can use the
pr revset to automatically pull and checkout GitHub pull request. For example,
sl goto pr123. See
sl help revsets for more info.
The GitHub website provides a way to turn a Git branch into a pull request.
You can use
sl push to create branches, then use the GitHub website to create
If you have write access to the repo, you can push to a new branch:
sl push --to remote/my-new-feature
If you don't have write access to the repo, you can fork the repo from the GitHub website, add your fork as a remote, then push to your fork:
sl paths --add myfork ssh://email@example.com/my-username/sapling.git
sl push --to myfork/my-new-feature
After push, open the repo webpage. You will see GitHub detected the push:
Click the "Compare & pull request" button to create a pull request.
You can also manually specify a Git branch and create a pull request. Read Creating a pull request from a fork for instructions.
To update an existing pull request, use
sl push -f to force push to the same
- Take control of commits (one or more) the pull request contains more explicitly.
- Use GitHub website to edit the pull request summary. It is easy to preview and auto-complete.
- Need a few more clicks on the GitHub webpage.
- Only create a single pull request per branch.
could not read Username error when trying to
If you see an error like the following:
stderr: fatal: could not read Username for 'https://github.com': No such device or address
Then you likely need to run
gh auth setup-git [--hostname HOST] to configure
gh as a Git credential helper. This will add the following to your
.gitconfig (though the host will be different if you used
--hostname to specify your GitHub Enterprise hostname):
helper = !/usr/bin/gh auth git-credential
helper = !/usr/bin/gh auth git-credential
See gh issue #3796 for details