
Type hinting is the process of annotating your code so that other developers reading your code will understand the type of an object declared. Type hinting was officially added with the release of Python 3.5. Currently, Python does not enforce type hinting when writing programs, but it is still a good practice to make your code more readable.

In this tutorial, we’ll go through a type hinting example with guidance on how to catch type hinting errors. Then, we’ll demonstrate how to use type hinting when initializing variables, how to use type hinting with user-generated values, and then how to use multiple or optional types. 

## A type hinting example function

First, let's start with this function. This math function is designed to take in two integers and return the sum.

```python
def sum_two_numbers(num1: int = 0, num2: int = 0) -> int:
    sum: int = num1 + num2
    return sum
```

In this example, both values passed into our `sum_two_numbers()` function — the sum object and return value — are all designated as integers, as indicated with `int` in each case. Default values come after the type hint for function parameters.

## Catching type hinting errors

Because the Python interpreter does not enforce type hinting, unexpected types can be passed to functions.

Let’s consider what happens when two strings get passed into the `sum_two_numbers()` function.

```python
def sum_two_numbers(num1: int, num2: int) -> int:
    sum: int = num1 + num2
    return sum

sum_two_numbers("Hello ", "World!")
```

Using the function like this would not throw an error. Instead, since the addition operator is valid for the string type, it will concatenate the two strings passed to it. Using the `sum_two_numbers()` function like this will return the string `Hello World!`.

If you would like to type check your code, you can use an external tool to do so, like [Mypy](http://mypy-lang.org/). You can use pip to install Mypy within your Python 3 programming environment (or alternately use the `pip3` command). 

```sh
pip install mypy
```

Let the previously written code be in a file called `sum.py`. You can run Mypy on the file by typing the following command.

```sh
mypy sum.py
```

Running Mypy on the code will return the following errors.

```
sum.py:4: error: Argument 1 to "sum_two_numbers" has incompatible type "str"; expected "int"
sum.py:4: error: Argument 2 to "sum_two_numbers" has incompatible type "str"; expected "int"
Found 2 errors in 1 file (checked 1 source file)
```

Code written with type hinting issues will not return any errors. If we put the first version of the `sum_two_numbers()` function that used integer types, we would instead receive the following output from Mypy.

```
Success: no issues found in 1 source file
```

Running Mypy on Python files will help you discover type checking errors.


## Initializing variables with type hinting

Python’s primitive types are included with general type hinting.

```python
my_int: int = 9
my_float: float = 2.2
my_string: str = "Hello World!"
my_boolean: bool = False
```

Each of these variables are initialized with type hinting as part of their declaration above.

## Collection types

Depending on the version of Python you are using, you may be able to leverage built-in typing across data structures, or you may need to import a module. In this section, we’ll go through how to hint type collection types in the two most recent versions of Python. 

### Python 3.9

In Python 3.9, built-in collection types are included as generic types and their respective type hints can be used similarly to the primitive Python types. Here is how you would type hint a list object in Python 3.9.

```python
my_list: list[int] = [1, 2, 3, 4, 5]
```

This list is initialized with the integer type by using the `list[int]` syntax.

Below is an example of a tuple that we have type hinted as being composed of an integer, float, and string.

```python
my_tuple: tuple[int, float, str] = (1, 9.5, "Red")
```
For a tuple object of unknown size, ellipses are used to describe the type of objects stored within it. Here is a tuple with an unknown number of integers stored.

```python
my_big_tuple: tuple[int, ...] = (1, 2, 3) 
```

It is possible to stack multiple types together as well. Here is a tuple that has sets of two integers.

```python
my_set: set[tuple[int, int]] = {(1, 2), (2, 3), (3, 4)}
```

Because we are working in Python 3.9 in these examples, we can set up these data structures as we did with other data types above, using the built-in functionality.

### Python 3.8

In Python 3.8, built-in collection type hints are not built directly into Python and must be imported to use. These types can be imported using the typing module. Using that module, below is how you would type hint a list object in Python 3.8. Note the use of title case in `List[int]`. 

```python
from typing import List

my_list: List[int] = [1, 2, 3, 4, 5]
```

Some other types in Python 3.8 that need to leverage the typing library include set, dictionary (`dict`), and tuple. Since both dictionary and tuple types can have multiple types involved, you must specify each type. Here is an example of a tuple that has an integer, float, and string.

```python
from typing import Tuple

my_tuple: Tuple[int, float, str] = (1, 9.5, "Red")
```
For a tuple object of unknown size, ellipses are used to describe the type of objects stored within it. Here is a tuple with an unknown number of integers stored.

```python
from typing import Tuple              

my_big_tuple: Tuple[int, ...] = (1, 2, 3)
```

You can also stack multiple types together as well, as in this tuple that uses two integers.

```python
from typing import Set, Tuple                           

my_set: Set[Tuple[int, int]] = {(1, 2), (2, 3), (3, 4)}
```

When working with Python 3.8, be sure to import the typing module prior to type hinting on data collections. Python 3.9 is backwards compatible, and will run the code above. 
## User-created types
It is also valid to type hint user-defined classes. In terms of type hinting, user-defined classes work in the same way as the primitive Python types. For example, here is a coordinate class definition and implementation.

```python
class Coordinate:
    x: int
    y: int

    def __init__(self, x_: int, y_: int) -> None:
        self.x = x_
        self.y = y_

c1: Coordinate = Coordinate(1, 2)
```

In the above example, the user-defined classes use type hinting. To learn more about the `-> None` annotation with `__init__`, review [PEP 484 - Type Hints](https://www.python.org/dev/peps/pep-0484/). 
## Multiple and optional types
As may happen with an application that takes user input, sometimes you may prefer for an object to be one of many types. This is possible using a union. 

Below is an example of how you would make the `sum_two_numbers()` function support both integers and floats.

```python
from typing import Union

def sum_two(num1: Union[int, float], num2: Union[int, float]) -> Union[int, float]:
    sum: Union[int, float] = num1 + num2
    return sum
```

In the example above, `num1` and `num2` can be either an integer or float type. 

If it is unclear what type an object is going to be, you can use the `Any` keyword to describe it.

```python
from typing import Any

my_variable: Any
```

In the above example, `my_variable` can be any type.

Some objects may have a value of `None`. To allow this, type hint using the `Optional` keyword to specify that a variable may have a defined value or be None.

```python
from typing include Optional

my_string: Optional[str] = None
```

This code will create a string object with the value of `None`.

## Additional resources

Read more about Python type hints in [PEP 484](https://www.python.org/dev/peps/pep-0484/) from the official Python documentation. 

Search open source code for type hinting in Python with Sourcegraph to learn how others are using this in their code. Here are a few queries to get you started.

<SourcegraphSearch query="-> None lang:python" patternType="literal"/>

<SourcegraphSearch query="List[int] = lang:python" patternType="literal"/>

Check out our other tutorials on [Sourcegraph Learn](https://learn.sourcegraph.com).


Type hints in Python programming

Type hinting in Python helps others understand and read your code

Getting started with type hinting in Python


Sourcegraph is actively working to index open source software so that developers can search all of the code that they care about. Being able to search across public repositories can help you learn open source best practices, inspect the libraries you may have as dependencies on your projects, and provide you with real-world examples you can leverage while you’re programming.

This tutorial will guide you through how to add public, open source repositories from GitHub and GitLab to Sourcegraph so that these code bases are indexed by the platform. Once you have added and synched these public repositories, anyone using Sourcegraph Cloud will be able to see results from these projects when they search all the code that is available through Sourcegraph via its global context.

To add public repositories to Sourcegraph, you’ll need a free Sourcegraph account, which you can set up by following our documentation on [getting started with Sourcegraph](https://docs.sourcegraph.com/getting-started#how-do-i-start-using-sourcegraph).

## Step 1 — Access user settings

Log into [Sourcegraph.com](https://sourcegraph.com) and click on your user icon on the top right corner of the page.

A drop-down menu will be displayed. From here, click on **Settings**.

![Sourcegraph home with user menu](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-home-user-menu.png)

You’ll be taken to a page that indicates that you are in your settings with a header of **User Settings** displayed towards the top of the page, and a panel with options regarding your user account on the left hand side of the window.

## Step 2 — Add repositories

From the panel on the left hand side of the interface, you can click on **Repositories** in order to be taken to the page where you can manage repositories. If you already have repositories added, you’ll need to click on the **Manage Repositories** button that is on this page in order to access this page.

![Sourcegraph manage repositories page](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-manage-repositories.png)

Within the **Manage Repositories** page, you’ll be presented with a few options:

- In the **Your repositories** section, you can sync _your own_ public repositories using GitHub or GitLab.
- In the **Other public repositories** section, you can add any public repositories on GitHub and GitLab.

For now, we’ll focus on the second option, and click the checkbox next to `Sync specific public repositories by URL`. Choosing this option, you can add any public repositories of code from either GitHub or GitLab, whether you contribute to the project or not.

Once you have clicked the checkbox, a check mark sign will appear in the box, like so: &#9745;. At this point, a box will display, similar to the screenshot below.

![Sourcegraph other public repositories list](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-other-public-repositories.png)

Within the box, you can type URLs of the public open source projects that you care about, one per line, with no separating characters other than the `ENTER` key.

The example above indexed the following two repositories, but you should choose repositories that are important to you, as these are already indexed:

- [github.com/prisma/women-world-wide](https://github.com/prisma/women-world-wide)
- [github.com/do-community/cloud_haiku](https://github.com/do-community/cloud_haiku)

When you are satisfied with the repositories that we have added for now (you can always add more later), you can click the **Save** button below.

## Step 3 — Search the repositories you added

At this point, you’re able to search the public repositories that you added. To verify this, you can scroll up to the top of the page where the Sourcegraph search bar is. To the left of the search bar it states `context:global`, which you can click on to limit it to your own username, to search the repositories you have added.

![Sourcegraph search with global context](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-context.png)

From here, you can search a common keyword to ensure that the public code you added is available to you.

To ensure that the public code you just added is available to anyone using Sourcegraph (even those not logged in), you can open a new private or incognito window and search for a fairly unique string to the code bases you have just added. In this case, we’ll search for `women world wide` to ensure that the `prisma/women-world-wide` repository is indexed:

<SourcegraphSearch query="women world wide"/>

![Sourcegraph verification of OSS added](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-anonymous-verification.png)

The screenshot above reveals output from the repository we just added to an anonymous user who is not logged in, which indicates that we have successfully added this public repository to Sourcegraph.

## Next steps

From here, you may want to sync your GitHub or GitLab account to add your own public repositories or forks.

With open source projects that are important to you fully indexed by Sourcegraph, you will be able to use libraries and other dependencies more effectively, and be able to summon up effective examples quickly while you’re building.


Learn how to add public, open source repositories to Sourcegraph.

How to add open source software projects to Sourcegraph cloud


Sourcegraph is a universal code search tool that can help you search all the code that is meaningful to you, whether that code is public and open source, or private to you or your team. 

---
**NOTE**:

_Searching private code is currently in Public Beta._

---

This tutorial will guide you through adding private repositories from a code host to Sourcegraph cloud so that you can search within and across your private code. 

**Your security and privacy are very important to Sourcegraph; Sourcegraph will have no access to see your private code and will never sell your private code. Only _you_ and your teammates with access to a given private repository via your code host will be able to see the private code you have added to Sourcegraph.**

To add your private repositories to Sourcegraph, you’ll need a free Sourcegraph account, which you can set up by following our documentation on [getting started with Sourcegraph](https://docs.sourcegraph.com/getting-started#how-do-i-start-using-sourcegraph).

## Step 1 — Access user settings

Log into [Sourcegraph.com](https://sourcegraph.com) and click on your user icon on the top right corner of the page. 

A drop-down menu will be displayed. From here, click on **Settings**.

![Sourcegraph home with user menu](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-home-user-menu.png)



You’ll be taken to a page that indicates that you are in your settings with a header of **User Settings** displayed towards the top of the page, and a panel with options regarding your user account on the left hand side of the window.

## Step 2 — Add private repositories

From the panel on the left hand side of the interface, you can click on **Repositories** in order to be taken to the page where you can manage repositories. If you already have repositories added, you’ll need to click on the **Manage Repositories** button in order to access this page.

![Sourcegraph repositories section under settings](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-repositories-section.png)



If you have no repositories yet, click on **+ Add repositories**. You’ll be presented with the option to connect with a code host in the **Your repositories** section. Here, you can sync _your_ repositories using GitHub or GitLab. This will include both your public repositories and your private repositories.

We’ll focus on adding private repositories. Click the `Connect code hosts` link and add GitHub, GitLab or both in order to connect with your software repositories.

Once connected, you’ll be able to sync all of your repositories or selected ones. You’ll be presented with a display of the repositories you have access to via your codehost, and will be able to click on the checkboxes to the left of their names in order to add them to Sourcegraph.

Depending on the code repositories you have access to, you may receive a list of both private and public repos. The ones that are private will be labeled with a `Private` tag to the right of the repository name. 

If you are part of an organization on a code host, an administrator will need to grant you access to private repositories there. For more information about this, please review our [troubleshooting guidance](https://docs.sourcegraph.com/code_search/how-to/adding_repositories_to_cloud#troubleshooting). 

In the image below, the `medieval-data` repository is a private repository, as indicated by the `Private` label.

![Sourcegraph repo list showing private label](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-repo-list-private-label.png)

You can also search for repositories by name, using the search bar labeled `Search repositories…`. 

Click the checkbox next to the private repositories you would like to add. In the image above, the `medieval-data` repository represents a checked checkbox. Next, scroll down to press the `Save` button at the bottom of the page. 

Once Sourcegraph has fully saved your selections, you should receive an output page that confirms all of the repositories you have saved to your account, both public and private.

![Sourcegraph list displaying all saved repos](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-list-of-saved-repos.png)

The image above shows 2 private repositories labeled with the `Private` tag and 5 public open source repositories that were also saved. For guidance on how to add open source software to Sourcegraph, review our tutorial, [How To Add Open Source Software Projects to Sourcegraph](https://learn.sourcegraph.com/how-to-add-open-source-software-projects-to-sourcegraph).

## Step 3 — Search your private repositories

At this point, you’re able to search all the private repositories you have access to that you added. To verify this, you can scroll up to the top of the page where the Sourcegraph search bar is. To the left of the search bar it states `context:global`. Instead, click on your own username (`@your-username`) to limit the search to your own repositories. 

![Sourcegraph search with context choice](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-context.png)

Next, further limit the context down so that you are only searching your private repositories. You can do this with the `visibility` command set to `private`. 

Let’s perform a search for the term `html` with the context set to our own username, and the command `visibility:private`.

![Sourcegraph visibility private code search](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-visibility-private-code-search.png)

The screenshot above reveals 15 results across the private repositories loaded into this Sourcegraph account.

You can perform a search similar to the one above with the Sourcegraph box below. Make sure you change the context to your own username:

<SourcegraphSearch query="visibility:private html"/>

Running a command like the one above across your own username will enable you to search across all of the private repositories that you have access to, providing you with all the benefits of universal code search.

## Next steps

You should now be able to search your private code in Sourcegraph cloud, a feature that is currently in public beta! If you had any issues in bringing in repositories, please review our [troubleshooting guidance](https://docs.sourcegraph.com/code_search/how-to/adding_repositories_to_cloud#troubleshooting). Note that organizations you are affiliated with will need to grant you relevant access. 

With your private code connected to Sourcegraph, you can learn more about how to search effectively by following along with our [Sourcegraph search series](https://learn.sourcegraph.com/how-to-search-code-with-sourcegraph-using-literal-patterns). You can also learn more about the product through reviewing Sourcegraph’s [product documentation](https://docs.sourcegraph.com/). 

For a video version of this tutorial, check out "[How to add private code repositories to Sourcegraph cloud (video)](/how-to-add-private-code-repositories-to-sourcegraph-video)."

Adding private software repos to Sourcegraph cloud

Learn how to add private software repositories to Sourcegraph.

How to add private code repositories to Sourcegraph cloud


Committing code with Git allows you to version control your own work, collaborate with other developers, and contribute to open source projects. GitHub Desktop is an application that provides a graphical interface to interact with Git repositories on your computer, providing an alternative to using Git on the command line. It can also clone, push, and pull remote repositories hosted on GitHub and elsewhere.

In this tutorial, we’ll go through how to commit code to a Git repository using GitHub Desktop.

## Prerequisites

Be sure that you have GitHub Desktop installed. You can install it by going to the [GitHub Desktop website](https://desktop.github.com/) and selecting the version of the software relevant to your operating system.

To follow this tutorial, you should already have a local Git repository on your computer and have made some changes that you want to commit. If you don’t yet have a Git repository on your computer, you can review the official documentation for “[Getting a Git Repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository).”

## Step 1 — Opening a repository in GitHub Desktop

If you have multiple local repositories, GitHub Desktop lets you switch between them to select the one you want to work on.

The name of the currently selected repository is displayed in the **Current Repository** tab in the top toolbar of the application. In the screenshot below, that repository is titled `javascript-demo`.

![The Current Repository tab showing the name of the current repository](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/github-desktop-current-repository.png)

This section will provide you with the steps needed to select your desired repository.

### Selecting a repository already present in GitHub Desktop

If you previously used GitHub Desktop to create or clone a repository or have manually added it, it will appear in the list of added repositories.

To select an added repository, open the **Current Repository** panel by clicking on it in the top toolbar. This will display a list of repositories that you can choose from.

![The Current Repository panel showing a list of repositories](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/github-desktop-repositories.png)

If the repository that you want to commit to is in the list, click on it to select it. Once your repository is selected, its name will appear on the **Current Repository** tab, and you can proceed to [Step 2 — Selecting a branch](#step-2--selecting-a-branch).

If the repository is not in the list, you’ll need to add it manually, as explained in the next section.

### Adding a local repository to GitHub Desktop

If you created or cloned your local repository with a tool other than GitHub Desktop, like the Git command-line interface, you’ll need to manually add your repository to GitHub Desktop to be able to access it in the application.

To add a local repository from your file system, open the **Current Repository** panel by clicking on it in the top toolbar and following these steps:

1. Click the **Add** button in the **Current Repository** panel.
2. Select **Add Existing Repository** in the dropdown menu.
3. Browse to the location of your repository in the file system.

![The Add Local Repository dialog box lets you choose a local repository.](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/github-desktop-add-repository.png)

Alternatively, you also have the option of cloning a remote repository hosted on GitHub or another source by selecting **Clone Repository** from the **Add** dropdown. This will also add it to the list of repositories.

After following these steps, your repository’s name should now appear under **Current Repository** in the top toolbar.

## Step 2 — Selecting a branch

Next, ensure that the current branch is the one where you intend to make your commit. The current branch is displayed on the **Current Branch** tab. You can click on this tab to switch branches or to create a new branch.

![The Current Branch tab displaying the `main` branch.](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/github-desktop-current-branch-tab.png)

If you want to create a new branch before committing, use the **New Branch** button in the **Current Branch** panel. Creating a new branch can be useful if you’re working on a new feature and want to keep your changes independent of the main branch, or if you’re making some experimental changes.

When thinking about creating and titling a new branch, consider having it describe what the new code will be doing. For example, if we’re planning to commit some changes to the `README.md` file in our repository, we could use the **New Branch** button to create a new branch and name it `update-readme`.

![The **Current Branch** panel in GitHub Desktop](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/github-desktop-current-branch.png)

Once we’ve selected a branch, its name will be displayed in the **Current Branch** tab.

## Step 3 — Selecting changes to commit

Before committing, you can choose which changed files you want to include in the commit.

The **Changes** panel lists every changed file in your working directory. The header of the list displays a file count, like “3 changed files,” as displayed in the screenshot below.

![The Changes tab showing the list of changed files.](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/github-desktop-changes.png)

Different types of changes are represented by icons to the right of each file name.

- Modified files are shown with a yellow dot in a square.
- Untracked (newly created files) files are shown with a green plus sign (`+`) in a square.
- Deleted files are shown with a red minus sign (`-`) sign in a square.

The top-most checkbox, found in the list header, allows you to select or deselect all files. You can also select files individually by using each file’s checkbox.

![Selecting files using the checkboxes in the file list.](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/github-desktop-changes-selected.png)

For example, in the screenshot above, we’re selecting two changed files (`demo.js` and `README.md`) by making sure their checkboxes are selected. We’re leaving the other file unselected, so it won’t be part of our commit.

## Step 4 — Writing a commit message and committing

In order to proceed to commit our changes, we need to provide a commit message. Each commit needs a commit message that describes the changes made. Commit messages are useful when browsing the history of commits in a repository, and they provide a summary of the changes made over time.

GitHub Desktop lets us provide the commit message in two parts:

- The **Summary** is a short one-line message that summarizes the changes in the commit.
- The **Description** is an optional, more detailed explanation that can be multiple lines long.

For example, we can write the following commit summary for our changed files:

```
Update README and demo script
```

We’ll enter this message into the **Summary** field. When committing complex changes, it can be useful to include more details in the **Description** field. This field is optional, so we can leave it blank.

![Entering a commit message into the **Summary** field.](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/github-desktop-commit-message.png)

With our changes selected and our commit message entered, we can now use the **Commit** button at the bottom to create the commit.

In the screenshot above, the button is labeled **Commit to update-readme** where `update-readme` is the branch that we previously selected. The name of your selected branch should be selected here.

When we click the **Commit** button, a new commit will be created, containing the staged changes. Those changes will disappear from the **Changes** panel, and the **Summary** and **Description** boxes will be cleared. Any unstaged changes will remain unstaged and available to be staged in future commits.

After clicking the **Commit** button, a message confirms that the commit was created, as in the screenshot below.

![The newly created commit displayed below the **Commit** button.](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/github-desktop-committed.png)

We can use the **History** tab to check what we’ve committed. We’ll do this in the next step.

## Step 5 — Checking the commit

To confirm that your commit was created successfully, you can check the history of commits to the repository and verify that your commit is present.

To open the history view, click on the **History** tab. This tab allows you to view the commits made to the repository, with the most recent commit at the top of the list.

![The log of commits in the history view, showing the last commit.](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/github-desktop-history.png)

In the above screenshot, the newly created commit is present at the top of the list. This confirms that it was created successfully and is now part of the repository.

## Learn more

In this tutorial, we created a commit using GitHub Desktop while also learning how to switch repositories, switch branches, and view the commit history.

To learn about other ways to commit code, you can read these tutorials:

- [How to commit code with the Git command-line interface](/how-to-commit-code-with-the-git-command-line-interface)
- [How to commit code to a Git repository with Visual Studio Code](/how-to-commit-code-to-a-git-repository-with-visual-studio-code)

You can also check out the [official Git project website](https://git-scm.com/).


Learn how to create commits in a Git repository with GitHub Desktop

How to commit code to a Git repository with GitHub Desktop


Committing code with Git is useful whether you’re working on your own projects, collaborating with others, or contributing to an open source project. Visual Studio Code is an open source IDE (Integrated Development Environment) with support for many programming languages. In addition to being a capable tool for writing and editing source code, VS Code can help you interact with Git repositories and commit changes. If you’re already using VS Code to edit code, it’s convenient to use the same tool to commit your changes with Git.

In this tutorial, we’ll demonstrate how to use the Git features within VS Code to commit code to a Git repository.

## Prerequisites

To follow this tutorial, you need Visual Studio Code installed on your computer. You can install it by following the instructions on the official [Visual Studio Code website](https://code.visualstudio.com/).

You also need Git installed. Visual Studio Code’s Git features depend on the Git command-line tools. You can install Git by following the instructions on the [“Installing Git” page of the official documentation](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).

With the above software installed, you should have created or identified a Git repository that you would like to contribute to. To make one of your local code repositories a Git repository, you can review the official documentation for “[Getting a Git Repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository)”.

## Step 1 — Preparing to make a commit

The **Source Control** panel in VS Code allows you to use Git features. It’s one of the panels that you can select in the **Activity Bar**, which is the vertical bar on the left side of the VS Code interface.

Each panel in the **Activity Bar** is represented by an icon. The **Source Control** icon is highlighted in the screenshot below.

![Location of the Source Control icon in the Activity Bar.](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/vs-code-source-control-icon.png)

Click on the icon to open the **Source Control** panel. This panel provides an interface to view the current changes in your working directory and to create new commits.

![The Source Control panel displays some changes in the repository.](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/vs-code-source-control-panel.png)

The **Changes** section of the panel lists all the files in the working directory that have been changed. The total number of changed files is also reflected on the **Source Control** icon’s badge. In the example in the above screenshot, the badge indicates that there are three changed files, and those three files are listed in the **Changes** section.

By selecting one of the files in the list, we can view the changes to that file. VS Code displays the changes as a **diff view** in a new editor tab. For example, if we select the `README.md` file, we can browse the changes as displayed in the screenshot below.

![An example of a diff view of the changes made to README.md.](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/vs-code-diff-view.png)

To prepare a commit, we will select changes to add to the staging area.

## Step 2 — Adding changes to the staging area

The **staging area** in Git is the collection of changes that will be included in the next commit. The next step is to add some changes to the staging area.

### Staging individual files

Each file in the **Changes** list represents a change in the repository’s working directory that has not yet been staged and is available for staging.

The badge next to each file indicates the type of change:

- The `M` badge indicates that a file is **m**odified. This means that it exists in the repository and has changed since the last commit.
- The `U` badge represents an **u**ntracked file, which means it doesn’t exist in the repository and was newly created since the last commit.
- The `D` badge means that the file was **d**eleted.

Each file has three action buttons. You can reveal these buttons by hovering over or clicking on a file in the list.

![Actions for each file in the Changes section.](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/vs-code-source-control-stage-file.png)

From left to right, the action buttons are:

- **Open File**, which opens the file in a new editor tab for editing.
- **Discard Changes**, which will discard the changes to this file, reverting it to the version from the latest commit.
- **Stage Changes**, which will add the file to the staging area for inclusion in the next commit.

To add a file to the staging area, click on its **Stage Changes** icon, represented by a plus (`+`) sign.

For example, we can stage the `README.md` file in the above screenshot by clicking on it in the list to reveal the action buttons and then selecting the plus (`+`) icon.

If we want to add more changes, we can repeat this process for other files. For example, we can continue by staging the untracked file, `getting-started.txt`. We can add as many changes to a commit as we want.

### Staging all files

In situations where we have many changed files and we want to stage them all, we can use the **Stage All Changes** button. This button is revealed by hovering over the title of the **Changes** section. Its icon is a `+` sign, as illustrated in the screenshot below.

![The actions revealed when hovering over the Changes title, from left to right: Discard All Changes and Stage All Changes, followed by the number of files changed (3).](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/vs-code-source-control-stage-all-changes.png)

After clicking the **Stage All Changes** button, all changed files in the list will be added to the staging area. This is a faster option than adding each file one by one.

## Step 3 — Checking the list of staged changes

After staging some changes, a new section will appear in the **Source Control** panel: **Staged Changes**.

After staging `README.md` and `getting-started.txt`, both files will now be present in the **Staged Changes** section and will no longer appear in the **Changes** section.

![The Staged Changes showing that the README.md file is staged.](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/vs-code-source-control-staged-changes.png)

If any changes remain in the **Changes** section when we commit, they will remain in the working directory and will be available to be staged for a future commit.

After checking that **Staged Changes** contains all the changes that we intend to commit, we can proceed to write a commit message.

## Step 4 — Writing a commit message and committing

Before we can commit our changes, we need to write a commit message. The commit message should describe the change being made. Commit messages are helpful when we’re browsing the history of a repository and trying to understand changes that were made in the past.

For example, we can write the following commit message for our changed files:

```
Update Readme and Getting Started docs
```

We’ll use the **Message** input box at the top of the **Source Control** panel to enter this commit message.

![Writing a commit message in the Message input box.](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/vs-code-source-control-staged-changes-with-message.png)

A common convention in Git is to limit the length of commit messages to a maximum of 50 characters. VS Code helps us follow this convention by showing a warning message if we exceed that length.

We’ll use the **Commit** button located at the very top of the **Source Control** panel to create the commit. This button appears as a check mark icon, as in the screenshot below.

![The Commit button at the top of the Source Control panel.](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/vs-code-source-control-commit-button.png)

When we click the **Commit** button, a new commit is created containing the staged changes. Those changes will disappear from the **Source Control** panel, and the commit message input box will be cleared. Any unstaged changes will remain unstaged and available for inclusion in future commits.

## Step 5 — Verifying the commit

To check that the commit was successful, we can view the commit log and confirm that our commit is present in the repository. Although VS Code doesn’t have a built-in way to display the commit log, we can display it by running a Git command in the terminal: `git log`.

Open the integrated terminal in VS Code by clicking on the **View** menu and clicking on **Terminal**. This should open a **Terminal** panel in the lower half of the window. The integrated terminal can also be opened with the keyboard shortcut: `Ctrl`-`` ` `` (Control and backtick).

To display the commit log in the terminal, run the `git log` command. By default, the command will display a scrollable list of all previous commits. In this case, we’re only interested in checking the latest changes we made, so we can provide the `-1` flag to the command to limit its output to one commit.

```sh
git log -1
```

Here’s the result of the command:

```
commit 5388e04d38e5de13e3968f8d5e1932a9b41e5e53 (HEAD -> main)
Author: Marek <marek@sourcegraph.com>
Date:   Tue Aug 31 18:47:11 2021 -0400

    Update Readme and Getting Started docs
```

In the above output of `git log -1`, we receive the commit ID and the branch name (`main`) on the first line. The output also includes the author and date, followed by the commit message.

Based on this output, we can conclude that the commit was successful and is now part of the repository.

## Learn more

In this tutorial, we learned how to commit changes to a Git repository with VS Code.

If you want to learn about committing code with the Git command-line tools, read [How to commit code with the Git command-line interface](/how-to-commit-code-with-the-git-command-line-interface).

To learn about ways that VS Code can integrate with Sourcegraph, watch our video about [How to integrate Sourcegraph into your workflows](/how-to-integrate-sourcegraph-into-your-workflows).


Learn how to create commits in a Git repository with VS Code.

How to commit code to a Git repository with Visual Studio Code

Commits are the fundamental building blocks of any Git repository. They’re the snapshots that represent the state of a repository’s files over time. Committing code with Git lets you collaborate with other developers, contribute to open source projects, and version control your own projects.

This tutorial will discuss how to create commits in the terminal using Git’s command-line tools. We’ll go through five steps: checking the repository status, selecting changes to be committed, checking the staged changes, creating the commit, and finally checking that the commit was successful.

## Prerequisites

This tutorial is suitable for those who already have a Git repository. It assumes that you’ve made changes to some files and that you want to commit those changes to the repository.

You will need to have the Git command-line tools installed and configured. For installation instructions, visit the [“Installing Git” chapter of the Git documentation](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).

The version of Git used in the examples in this tutorial is 2.32.0. You can check that you have Git installed and verify its version by running `git version` in your terminal.

```sh
git version
```

You’ll receive output similar to the following, which states your version number.

```
git version 2.32.0
```

Note that when talking about Git, the word “commit” can be used both as a noun (as in: “Here is the latest commit.”) and a verb meaning “to create a commit” (as in: “I will commit this change.”).

## Step 1 — Checking the repository status

First, it’s useful to get a summary of the changes that we’ve made in our project’s working directory. This will help us select the changes that we want to add to our commit. Run the `git status` command:

```sh
git status
```

The output of the command tells us about the changes that are available to be added to our commit. The first section of the output that we’ll pay attention to is titled `Changes not staged for commit`.

```
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   README.md
```

This section lists files that already exist in the repository and have been modified since the last commit. It tells us that we have one modified file, `README.md`.

The second section that is relevant to us is titled `Untracked files`. It lists newly created files that don’t yet exist in the repository.

```
Untracked files:
  (use "git add <file>..." to include in what will be committed)
        getting-started.txt
```

The above output tells us that there’s one new file in the working directory, `getting-started.txt`.

After reading the output of `git status`, we can proceed to select the changes that we want to commit, and we’ll do that by adding those changes to the staging area.

## Step 2 — Selecting changes to be committed

In a Git repository, the **staging area** is the collection of changes that will be included in the next commit. Before we can commit our changes, we have to stage the changes we intend to include in the commit.

### Adding a modified file to the staging area

To add a modified file to the staging area, we use the `git add` command. The `git add` command, in its simplest form, expects a file name as an argument. Here’s an example in which we add the file named `README.md` to the staging area:

```sh
git add README.md
```

If we run `git status` again at this point, `README.md` will be gone from the “Changes not staged for commit” section and will instead be present under “Changes to be committed.” This confirms that it has been added to the staging area.

We can continue by adding more files using `git add`. For example, we’ll add the newly created file, `getting-started.txt`:

```sh
git add getting-started.txt
```

After this command, `getting-started.txt` will also be included in the “Changes to be committed” section of the `git status` output. By using `git add` in this way, we can include as many changed files as we want in our commit.

### Adding all current repository changes to the staging area

Rather than adding each changed file one by one to the staging area, a common alternative is to add all changed files in one command. This applies to situations where we don’t want to selectively choose which changes to commit because we want the commit to be a snapshot of the entire working directory.

We can add all files by providing the `-A` flag (which is short for `--all`) to `git add` instead of specifying a file name:

```sh
git add -A
```

The above command will recursively add all the repository's modified files in all subdirectories to the staging area, regardless of where we are running the command. We can run this from any location within the repository.

### Removing changes from the staging area

It’s possible to remove changes from the staging area using the `git restore` command. This is useful if you change your mind about what changes you want to commit or have accidentally added some files that you didn’t intend to add.

The `git restore` command expects a file name, similarly to `git add`, and requires the `--staged` flag to indicate that we intend to unstage a file that is currently staged. Here’s an example:

```sh
git restore --staged README.md
```

This will remove `README.md` from the staging area. The changes to the file won’t be lost. They will remain in the working directory.

## Step 3 — Checking staged changes before committing

Once we’ve selected the changes that we want to commit, it’s a good idea to check the status of the repository again. This helps us confirm that the changes we’re about to commit are the ones we intend to commit.

Now that we’ve added two files, `README.md` and `getting-started.txt`, we can check the status of the repository by running `git status` again. The output now includes a section called `Changes to be committed`:

```
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   README.md
        new file:   getting-started.txt
```

The output confirms that we have two changes in the staging area: `README.md`, which is modified, and `getting-started.txt`, which is new.

If we have any other modified files that we haven’t staged, they will be present in the `Changes not staged for commit` section. These changes won’t be included in the commit and will remain in the working directory after the commit is created.

## Step 4 — Creating the commit

To create a commit, we use the `git commit` command, which will perform these tasks:

- Create a new commit on top of the latest commit in the current branch.
- Move all staged changes into the new commit.
- Attach the date, author, and message to the new commit.
- Update the current branch to include the new commit.
- Clear the staged changes from the staging area.

Before we can run the command, we need to write a commit message.

### Writing a commit message

The commit message is an important piece of information that we need to provide to the `git commit` command. The commit message is the text that describes the changes that we’re making.

Commit messages are helpful when you’re browsing through the commit history of a project. They show you, at a glance, the sequence of changes made to the project. It’s common to browse commits by looking at the log of each commit’s message, date, and author.

Suppose that we’re committing changes to update the `README.md` file and add a `getting-started.txt` file. Our commit message could be:

```
Update README and add getting-started file
```

We’ll use this message with the `git commit` command in the next step.

### Committing

Having a commit message in mind, we’re now ready to run the `git commit` command.

We specify the commit message by providing it as an argument to `git commit`. The message should be a string in quotes preceded by the `-m` flag, which stands for “message.”

With our example commit message, the command would look like this:

```sh
git commit -m “Update README and add getting-started file”
```

Here’s the output when we run this command:

```
[main 5388e04d38] Update README and add getting-started file
 2 files changed, 1 insertion(+), 1 deletion(-)
 create mode 100644 getting-started.txt
```

The above output tells us a few things about the commit that we just created: the number of files changed, the number of insertions and deletions (which is a count of lines affected), and the list of created files.

Because `git commit` acts on our local file system and doesn’t automatically send our commit anywhere, we’ll need to use the `git push` command to push our commit to a remote repository such as GitHub.

## Step 5 — Checking the commit

After running `git commit`, we can check that it was created successfully with the `git log` command.

The `git log` command outputs a list of recent commits. Since we’re only interested in checking the last commit, we can shorten the output by adding the `-1` option, which will display only the most recent entry.

```sh
git log -1
```

This helps us confirm that the last commit is, in fact, the one that we just created. Here’s the result when we run `git log -1` after creating our commit:

```
commit 5388e04d38e5de13e3968f8d5e1932a9b41e5e53 (HEAD -> main)
Author: Marek <marek@example.com>
Date:   Tue Aug 31 18:47:11 2021 -0400

    Update README and add getting-started file
```

In the above output of `git log -1`, we see the commit ID and the branch name (`main`) on the first line. The output also includes the author and date, followed by the commit message.

Based on this output, we can conclude that the commit was successful and is now part of the repository.

## Learn more

In this tutorial, we explored how to create Git commits with command-line tools. There are other ways to create Git commits, and there are many tools that can facilitate the task.



Visit the [Sourcegraph Learn home page](/) for more educational resources.

Learn how to create commits with the Git command-line tools in the terminal.

How to commit code with the Git command-line interface


With a self-hosted instance of Sourcegraph, you can search your local code, and the code that you and your team collaborate on in repositories held within code hosts like GitHub and GitLab. 

In order to use a self-hosted instance of Sourcegraph, you’ll need to create an account. This tutorial will provide you with guidance on creating an account with Sourcegraph.

## Prerequisites

Before setting up an account on a self-hosted instance of Sourcegraph, you will need to set up your own instance of Sourcegraph, or be invited to join one. 

If you need to install and set up an instance of Sourcegraph, you can review our [installation guides on Sourcegraph Learn](https://learn.sourcegraph.com/tags/installation), or read through our [documentation on installation](https://docs.sourcegraph.com/admin/install). 

With access to a Sourcegraph instance, you can get started.

## Step 1 — Navigate to the URL of your instance of Sourcegraph

If you are invited to use an instance of Sourcegraph, ask an administrator to create an account for you, or set up a sign on process to access the instance.

If you have just set up your own instance of Sourcegraph, you should have received output on your terminal for the relevant IP address and port created to access Sourcegraph.

![Sourcegraph terminal output after installation](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-logo-terminal.png)

```
Sourcegraph is ready at: http://the-server-ip-address:7080
```

Using your preferred browser, navigate to the relevant IP address or URL. At this point, you should be at the signup screen if you have not made an account already.

## Step 2 — Sign up with your email address

Once you have navigated to the IP address or URL of your Sourcegraph instance, you should be at the signup page if you don’t already have an account. 

![Sourcegraph self-hosted instance login page](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-login-page.png)

From this page, you’ll be able to sign up with your email address, then create a username and password. 

Note that if you have navigated to a Sourcegraph instance that you were not invited to, you will receive this page and will need to contact the administrator of the relevant instance.

![Sourcegraph instance login, need to contact site administrator if you don’t get the signup page](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-contact-site-admin.png)

You will need to use a valid email address that you can access. If you use an invalid email address, you will receive a descriptive error message to troubleshoot your account creation. Enter your email address in the **Email** field of the signup form. 

Once your email address is accepted, you can choose your preferred username in the form input section labeled **Username**. Only alphanumeric characters are permitted within the username.

Next, create a password. A password adds a layer of security to your account by preventing unauthorized access. Your chosen password should be at least 12 characters. Enter a secure password in the form input section labeled **Password**, and make a note of it.

After filling the form with a valid email address, username, and password, click on the button at the bottom of the form to create an account and continue.

## Step 3 — Verify that your account was created

Once you have created your account successfully, you will be taken to your account overview page. 

![Sourcegraph overview page after account creation](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-overview-page-after-account-creation.png)

From here, you can begin completing the onboarding process by adding repositories, searching your code, finding some references, and configuring SSO or adding teammates. You can review all of our [administration documentation](https://docs.sourcegraph.com/admin) to learn more.

## Next steps

Now that you have created a Sourcegraph account, you can start searching the code that is important to you.

For some introductory tips, check out our video on the [three ways to search with Sourcegraph](https://learn.sourcegraph.com/three-ways-to-search-code-with-sourcegraph). You can also review all of our [search tutorials](https://learn.sourcegraph.com/tags/search).

If you have installed your instance of Sourcegraph and created an account, and want to upgrade to an enterprise version to allow your team to use more advanced code search features, you can look at our [enterprise getting started guide](https://docs.sourcegraph.com/adopt/enterprise_getting_started_guide) to help you begin.


Search your code with a Sourcegraph account

Create an account on self-hosted Sourcegraph to your code

How to create a self-hosted Sourcegraph account


Sourcegraph cloud lets you search across open source software and your private repositories hosted on GitHub or GitLab in a web browser. To begin using Sourcegraph cloud, you can navigate directly to [sourcegraph.com](https://sourcegraph.com) and begin searching the code that Sourcegraph has already indexed. If you would like to save your search history or to connect your public or private repositories on GitHub or GitLab, you will need to create a Sourcegraph cloud account.

**_Note that searching private code on Sourcegraph cloud is currently in Public Beta._**

There are three ways to sign up for a Sourcegraph cloud account, which will be detailed in the sections below. Feel free to skip ahead to your preferred method of signing up:

* [Creating a Sourcegraph cloud account with GitHub](#creating-a-sourcegraph-cloud-account-with-github)
* [Creating a Sourcegraph cloud account with GitLab](#creating-a-sourcegraph-cloud-account-with-gitlab)
* [Creating a Sourcegraph cloud account with an email address](#creating-a-sourcegraph-cloud-account-with-an-email-address)

Open your browser of choice, and we can get started.

## Navigate to the Sourcegraph cloud sign up page

In your browser address bar, type in [sourcegraph.com](https://sourcegraph.com). When the page is fully loaded, you’ll receive a page similar to the following, with Sourcegraph’s logo and a search bar.

![Sourcegraph cloud homepage](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-cloud-landing.png)

On the right-hand side of the top navigation pane, there is a **Sign up** button that takes you to the [account creation](https://sourcegraph.com/sign-up) page. The **Sign up** page is where you can create an account.

![Sourcegraph cloud signup page](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-cloud-signup-landing.png)

From here, you can continue to signing up through your option of choice.

## Creating a Sourcegraph cloud account with GitHub

To use GitHub authentication, from the **[Sign up](https://sourcegraph.com/sign-up)** page, click on the **Continue with GitHub** button. Clicking on the GitHub button will take you to GitHub’s login page if you are not already logged in.

![Create a Sourcegraph cloud with GitHub](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/github-login-to-access-sourcegraph.png)

Once you are logged into GitHub, you will be directed to a page that requires you to authorize Sourcegraph. The authorization you will be giving to Sourcegraph will allow Sourcegraph to access the GitHub details mentioned in the signup form for your account creation. 

![Authorize Sourcegraph cloud with GitHub](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/authorise-sourcegraph-on-github.png)

If you choose to authorize Sourcegraph, you will be redirected to Sourcegraph cloud’s welcome page. By completing these steps, you have successfully created a Sourcegraph cloud account using GitHub.

## Creating a Sourcegraph cloud account with GitLab

If you have a GitLab account and would prefer to create a Sourcegraph account that is tied to your GitLab account, click on the **GitLab** button on Sourcegraph cloud’s **[Sign up](https://sourcegraph.com/sign-up)** page.

If you are not signed into your GitLab account, you will be redirected to log into GitLab to continue.

![Login to GitLab](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/gitlab-login.png)

If you are logged into GitLab, you will need to login so that you can authorize GitLab as the method to create a Sourcegraph cloud account.

![Authroize Sourcegraph cloud with GitLab](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/authorize-sourcegraph-on-gitlab.png)

Clicking on **Authorize** will allow Sourcegraph to have access to the GitLab details that are mentioned in the signup form for your account creation.

If you choose to authorize Sourcegraph, you will be redirected to Sourcegraph cloud’s welcome page. By completing these steps, you have successfully created a Sourcegraph cloud account using GitLab.

## Creating a Sourcegraph cloud account with an email address

To create a Sourcegraph account by providing an email address, you will need to use a valid address that you can access. 

On the **[Sign up](https://sourcegraph.com/sign-up)** page, there is a [continue with email](https://sourcegraph.com/sign-up?showEmail=true) link below the code host buttons. Clicking on this link takes you to a form where you can create an account using an email address. Enter the valid email address you would like to use in the form input space labeled **Email**.

![Sourcegraph cloud signup with email form](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-cloud-signup-email-field.png)

An invalid email address will throw an error message and will not let you complete the account creation process.

Each Sourcegraph username that is tied to an email address will need to be unique, as there are no two users with the same username on Sourcegraph cloud.

Enter your preferred username in the form input section labeled **Username**.

![Sourcegraph cloud valid username field with email signup](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/username-field-sourcegraph-signup-form.png)

If the username you have chosen is in use by another user, there will be an error that indicates that the username is taken. In this case, you can modify your preferred username to continue.

Next, create a password. A password lets you add a layer of security to your account by preventing unauthorized access.

When creating a Sourcegraph account, your chosen password should be at least 12 characters. Enter a secure password in the form input section labeled **Password**.

After completing the three steps above completely, you can click on the **Register** button to create an account. At this point, you will be taken to the welcome page of your account.

## Security on Sourcegraph cloud

Your security and privacy are very important to Sourcegraph; Sourcegraph will have no access to see your private code and will never sell your private code. Only you and your teammates with access to a given private repository via your code host will be able to see the private code you have added to Sourcegraph.

Read more about Sourcegraph and privacy on our [privacy page](https://about.sourcegraph.com/privacy/).

## Next steps

Now that you have created a Sourcegraph cloud account, you can start using Sourcegraph cloud to search the code that is important to you by having a look at our [cheat sheet guide](/how-to-search-code-with-sourcegraph-a-cheat-sheet).

You may also want to check our video on the [three ways to search with Sourcegraph](/three-ways-to-search-code-with-sourcegraph) to learn the different ways you can use Sourcegraph to search your code.


Search code in a browser with a Sourcegraph cloud account

Create a Sourcegraph cloud account to search open source and private repos

How to create a Sourcegraph cloud account

With tech-focused podcasts increasing in popularity within the developer community, it is valuable to know how to distribute one effectively. It is imperative to be able to reach listeners through platforms such as Apple Podcasts, Google Play, and Spotify. 

In this tutorial, we will use the example podcast, _The Open Ollie Show_, which is about all things open source hosted by Ollie, the open source kitty.

We will first walk through hosting the audio files for each episode on a cloud object storage service, for us to include in the RSS feed we create. Then, we will write the RSS feed line by line using XML, bringing our episodes together and providing various data for platforms to use. Finally, we will validate the RSS feed and submit it to Spotify so that we can distribute our tech podcast using their platform in order to reach our listeners.

## Prerequisites

In order to follow the steps of this tutorial, you should have the following:

* One or more episodes recorded, edited, and ready to be published to the public as an MP3 audio file.
* Server space which will host the audio files for each episode. We recommend using a cloud object storage service that is S3-compatible and has a CDN.
* An image (sized between 1400x1400 pixels and 3000x3000 pixels) that will serve as the podcast’s logo.

With these prerequisites in place, let’s begin. 

## Step 1 — Uploading audio files to object storage

We will begin by uploading our first episode’s MP3 audio file to our cloud object storage. You can use any cloud data store that makes sense for you, we’ll be using an S3-compatible storage. If you already have your file uploaded in a publicly-accessible data store with CDN, feel free to skip this step. We’ll be demonstrating how to do this with the S3-compatible buckets available via Google Cloud Platform and DigitalOcean. Feel free to use an alternate provider, the steps may differ across hosts, so be sure to follow recommended practices from their respective official documentation. 

### Uploading a podcast MP3 to Google Cloud Platform

For this tutorial, we created an `open-ollie-show` bucket on Google Cloud Platform Cloud Storage. If you need help setting up and uploading files, review this [tutorial on uploading objects to Cloud Storage](https://cloud.google.com/storage/docs/uploading-objects). 

From your bucket’s main page, choose whether you want to put your file in your root or other directory, then navigate there. We called our file `episode1.mp3`. From the directory you want to upload the file to, select the **Upload Files** link or else drag and drop your file into the bucket. 

Click on the `episode1.mp3` file that you just uploaded and copy the link given next to **Public URL**. Now that we have our file’s URL saved we can go ahead and begin writing our podcast’s RSS feed.

### Uploading a podcast MP3 to DigitalOcean Spaces

For this tutorial, we created an `open-ollie-show` Space on DigitalOcean. If you need help setting up a Space, review this [DigitalOcean Spaces tutorial](https://www.digitalocean.com/community/tutorials/how-to-create-a-digitalocean-space-and-api-key).

Starting on the **Files** tab on our Space’s web page we will press the **Upload Files** button and select our MP3 file from our computer. When asked to set the file as privately or publicly readable, select *Public* so that listeners will be able to stream our audio file.

The file we uploaded was named `episode1.mp3` to make it easier to reference when writing our RSS feed. We can always rename any file we upload by pressing the **More** dropdown on the file we want to rename.

We will need to save the link to our first episode’s file for later by hovering over the file and pressing **Copy URL**. Our Space has CDN enabled, so we will copy our Edge URL. That said, the Origin URL would also work. Now that we have our file’s URL saved we can go ahead and begin writing our podcast’s RSS feed.

## Step 2 — Writing the RSS feed


Next, we’ll be creating our RSS feed. You can title your RSS feed after your podcast. In our example podcast, we’ll call it `open-ollie.rss`.
RSS feeds are written within an XML document. Therefore, we will begin by writing an XML declaration followed by an opening and closing RSS tag in which we will define our XML namespace.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd" xml:lang="en" version="2.0">

</rss>
```    

The first line in our code above is our XML declaration. 

The second line is our opening RSS tag which will include all of our content and, consequently, the rest of the code we write throughout this tutorial. Within this opening tag we defined our XML namespace using the “xmlns” attribute. Because this RSS feed will be used for a podcast, we declared that we will be using the iTunes podcast namespace which is a generic namespace useful for platforms such as Apple Podcasts, Google Play, and Spotify. Without this, many other tags we define will not be parsed correctly.

Next, let’s define our podcast show using the `<channel>` tag as shown in the XML below.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd" xml:lang="en" version="2.0">
    <channel>
        <title>The Open Ollie Show</title>
        <link>learn.sourchegraph.com</link>
        <description>A podcast about open source repositories hosted by Ollie the Open Source Kitty.</description>
        <language>en</language>
        <itunes:image href="https://i.imgur.com/zvFIqdf.png" />
        <itunes:author>Open Ollie</itunes:author>
        <itunes:owner>
            <itunes:name>Open Ollie</itunes:name>
            <itunes:email>OpenOllie@email.com</itunes:email>
        </itunes:owner>
        <itunes:explicit>no</itunes:explicit>
        <itunes:category text="Technology"/>

    </channel>
</rss>
```

The following tags are used to help describe our podcast further:

| Tag | Description |
|---|---|
| `<title>` | The title of our podcast show, this is separate from the titles of each episode |
| `<link>` | A link to our podcast, this can be a seperate website, or a link to the Spotify page or anywhere else we decide to distribute our podcast |
| `<description>` | A sentence or two describing what our podcast is about |
| `<language>` | Specifies the language we will be speaking in our podcast, in this case it’s `en` for English, you can find the relevant two-letter language code relevant to you in the [ISO 639.2 standards document](https://www.loc.gov/standards/iso639-2/php/code_list.php) |
| `<itunes:image>` | The logo of the podcast (this must be between 1400x1400 pixels and 3000x3000 pixels) |
| `<itunes:author>` | The publicly displayed author or host of the podcast |
| `<itunes:owner>` | The name and email of the owner of the podcast which is kept private and may be used in case Apple, Spotify, or any other platform needed to contact us |
| `<itunes:explicit>` | Set to `yes` if any vulgar language is used throughout our podcast and `no` if no vulgar language is used |
| `<itunes:category>` | Which category Apple Podcasts would put our podcast under if we choose to distribute using their platform; see a [list of available categories via Apple](https://help.apple.com/itc/podcasts_connect/#/itc9267a2f12) |


Now, it is time to add our first episode to our podcast which we will do using an `<item>` tag. All episodes we define will be inside of their own `<item>` tag and because this can get messy once you have multiple episodes, we will be using line spacing and comments to help us keep this straightforward to read for ourselves and anyone else who looks at our RSS feed in the future.

Starting two lines below our `<itunes:category>` tag, as shown below, we will begin to define our first episode.

```xml
    <channel>
        ...
        <itunes:category text="Technology"/>
        
        
        <item>
            <title>Episode 1: Life as a Keyboard Cat</title>
            <description>Ollie the Open Source Kitty discusses their approach to programming open source software with their paws.</description>
            <link></link>
            <enclosure type="audio/mpeg" url="https://sammys-podcast.nyc3.cdn.digitaloceanspaces.com/episode1.mp3"/>
            <guid isPermaLink="false">dcc051a2-adc9-4e6e-9fd3-ecbec2f7cf72</guid>

        </item>
    </channel>
```

We begin by defining the title of this podcast episode as shown above using the `<title>` tag along with a brief summary of the episode using the `<description>` tag.

Next, we use the `<link>` tag to either link to the podcast episode hosted on an external site or input the url to the MP3 file on our Space (this option being the one we chose for The Open Ollie Show). This is followed by the `<enclosure>` tag which is where Spotify will pull our episode’s MP3 file for listeners to stream. The `type` attribute is used to specify that we are providing an MP3 file and the `url` attribute is the episode file’s URL which we saved earlier from uploading our MP3 to our Space.

Finally, we set a global unique identifier using the `<guid>` tag. This is to make sure that if we ever change the title of this episode, Spotify will be able to understand that we are only changing the title of an existing episode instead of making a whole new episode that has the same audio file. We used an online UUID generator in order to get a random string that we will use as the unique identifier. Because this is not a permalink to our podcast, we will set the `isPermaLink` attribute to false.

Let’s finish defining the rest of our first episode.

```xml
    <channel>
        ...
        
        <item>
            ...
            <itunes:duration></itunes:duration>
            <itunes:author>Open Ollie</itunes:author>
            <itunes:explicit>no</itunes:explicit>
            <itunes:season>1</itunes:season>
            <itunes:episode>1</itunes:episode>
            <itunes:episodeType>full</itunes:episodeType>
            <pubDate>Wed, 1 Jan 2020 12:00:00 +0000</pubDate>
        </item>
    </channel>
```

Now that the initial XML declarations are complete, we have now set a few extra variables which are explained below.

| Tag | Description |
|---|---|
| `<itunes:duration>` | The duration of our episode in seconds |
| `<itunes:author>` | tThe author or host of this specific episode, notice this can be different from the overall show author |
| `<itunes:explicit>` | Whether or not this episode uses any vulgar language, notice this is also different from the overall show setting |
| `<itunes:season>` | In case you ever want to have multiple seasons for your podcast it is good to specify a season for each episode, even if it will always be season 1 |
| `<itunes:episode>` | Which episode number this is for the aforementioned season number |
| `<itunes:episodeType>` | `full` specifies that this is a full length episode; we can also use `bonus` to specify this as bonus content which is separate from our regular episodes. Bonus content can have the same season and episode number as a full episode. This is useful if our bonus content is a clip from a longer full episode |
| `<pubDate>` | Used for ordering our podcast episodes, the date above sets this episode’s publish date and time to Wednesday, January 1st, 2020 at noon UTC |


At this point, we can save our XML RSS feed file and submit it to our distributors.

## Step 3 — Submitting the podcast for review on Spotify

Now that we have created our RSS feed and uploaded our first episode and RSS feed to our cloud object storage bucket, we can submit our podcast and its first episode to Spotify for our listeners to enjoy.

Start by creating a [free Spotify account](https://accounts.spotify.com/en/login?continue=https:%2F%2Fpodcasters.spotify.com%2Fgateway) if you do not have one already. To keep things intuitive, we will use the same email for the Spotify account that was used in the `<itunes:email>` tag in the RSS feed.

Next, we will go to [Spotify’s podcast submission page](https://podcasters.spotify.com/submit) and press *Get Started* followed by pasting the link to our RSS feed hosted on the cloud of our choice in the *Link to RSS feed* field that we discussed in [Step 1](#step-1--uploading-audio-files-to-object-storage).

All that is left is inputting our podcast’s details including category, language, and country, and finally reviewing our podcast’s information and submitting our podcast.

## Next steps

Once you have everything set up for your RSS feed, you can focus on recording your podcast! If you would like to learn more about RSS for podcasters, you can review Apple’s [A Podcaster’s Guide to RSS](https://help.apple.com/itc/podcasts_connect/).

How to distribute a podcast using an RSS feed


Sourcegraph is a tool that can allow you to search all the code that is important to you, from your own local repositories, to the software you build together with a team, to all the code that is available through open source projects. You can get started using Sourcegraph by using [Sourcegraph cloud](https://sourcegraph.com/search) with your preferred web browser, or you may want to install your own instance of Sourcegraph locally or on a cloud server or virtual machine.

By installing Sourcegraph on your own hardware, you’ll be able to manage your own instance of Sourcegraph, providing you with complete control over who has access to your code. Your own installation will also allow you to connect your local (or server-side) code as well as any relevant Git servers. Git servers that you can connect to include GitHub, GitHub Enterprise, GitLab, Bitbucket, AWS CodeCommit, Perforce, and more.

We’ll go through how to install Sourcegraph on your local Linux machine with Docker so that you can begin to use Sourcegraph on all of your code. This installation guide is appropriate for local testing and should be quick to set up. If you would like to use Sourcegraph in a production environment, you should follow our documentation on installing Sourcegraph with [Docker Compose](https://docs.sourcegraph.com/admin/install/docker-compose) on a single node, or on a [Kubernetes cluster](https://docs.sourcegraph.com/admin/install/kubernetes).

## Step 1 — Install Docker

_If you already have Docker installed, you can [skip to the next step](#step-2--install-sourcegraph)._

On a Linux cloud server or local computer, you can install Docker via the command line as long as you are a user with super user privileges. We’ll go over how to install Docker across [Ubuntu and Debian](#ubuntu-and-debian), [Fedora](#fedora), and [CentOs](#centos) Linux distributions in this section. Skip down to the section that is relevant for the machine you’re using to install Sourcegraph.

### Ubuntu and Debian

Ensure that you have the [snap package manager](https://snapcraft.io/) installed by running the following commands in your terminal for **Ubuntu or Debian Linux**:

```sh
sudo apt update
sudo apt install snapd
sudo snap install core
```

Once snap is fully installed, you can install Docker using snap.

```sh
sudo snap install docker
```

Alternatively, you can install Docker through its packages available through the Docker installation page for [Ubuntu](https://docs.docker.com/engine/install/ubuntu/) or for [Debian](https://docs.docker.com/engine/install/debian/).

With Docker installed, you are ready to procceed to [Step 2](#step-2--install-sourcegraph).

### Fedora

If you are using **Fedora**, ensure that snap is installed by running the following command:

```sh
sudo dnf install snapd
```

Once you confirm that snap is fully installed, you can install Docker using snap.

```sh
sudo snap install docker
```

Alternatively, you can install Docker through its packages available through the [Docker installation page for Fedora](https://docs.docker.com/engine/install/fedora/).

With Docker installed, you are ready to procceed to [Step 2](#step-2--install-sourcegraph).

### CentOs

If you are using **CentOs**, you can ensure that snap is installed and ready by running the following commands. For more guidance on these commands, please visit snap’s [official documentation](https://snapcraft.io/install/docker/centos).

```sh
sudo yum install epel-release
sudo yum install snapd
sudo systemctl enable --now snapd.socket
```

Once you confirm that snap is fully installed, you can install Docker using snap.

```sh
sudo snap install docker
```

Alternatively, you can install Docker through its packages available through the [Docker installation page for CentOs](https://docs.docker.com/engine/install/centos/).

With Docker installed, you are ready to install Sourcegraph.

## Step 2 — Install Sourcegraph

Depending on the machine that you have, you’ll be able to run a Docker command to install Sourcegraph and get up and running with code search on your local repositories and beyond.

We’ll go over two approaches below; the first which is recommended for [Linux running on a local machine](#locally-on-linux), the second option is recommended for [Linux cloud servers](#on-a-linux-server).

### Locally on Linux

On local machines that use a Linux distribution, you’ll be able to install Sourcegraph by running the following Docker command.

```sh
docker run --publish 7080:7080 --publish 127.0.0.1:3370:3370 \
--rm --volume ~/.sourcegraph/config:/etc/sourcegraph \
--volume ~/.sourcegraph/data:/var/opt/sourcegraph \
sourcegraph/server:3.30.4
```

This command is telling your computer to install and run Sourcegraph in port 7080 of your localhost (127.0.0.1) and is calling up the relevant files from the Docker image of Sourcegraph. It is also setting up a store for your Sourcegraph data.

Once you run the command, you’ll receive some output indicating that Sourcegraph is getting set up. Sourcegraph will be ready when you receive the output similar to the following:

```sh
✱ Sourcegraph is ready at: http://127.0.0.1:7080
```

At this point, you’ll be able to move onto the next section to verify your installation.

### On a Linux server

On a Linux cloud server, you can run the following command to keep your instance of Sourcegraph up and running even after you close your Terminal connection to the server.

```sh
docker run -d --publish 80:7080 --publish 443:7443 \
--restart unless-stopped \
--volume /root/.sourcegraph/config:/etc/sourcegraph \
--volume /root/.sourcegraph/data:/var/opt/sourcegraph \
sourcegraph/server:3.30.4
```

This command is telling your server to install and run Sourcegraph in port 7080 of your server and is calling up the relevant files from the Docker image of Sourcegraph. It is also setting up a store for your Sourcegraph data.

Once you run the command, you’ll receive some output indicating that Sourcegraph is getting set up. Sourcegraph will be ready when you receive output similar to the following. Your server’s IP address will display in place of `your-server-ip-address`.

```sh
✱ Sourcegraph is ready at: http://your-server-ip-address:7080
```

At this point, you’ll be able to move onto the next section to verify your installation.

## Step 3 — Verify the installation

When Sourcegraph is fully installed and ready to be used, the Sourcegraph logo will appear and you should access the URL that is indicated in the Terminal output.

![Installation complete verification on command line](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-logo-terminal.png)

Open a browser and go to the URL indicated in the output. Keep in mind that if you are using a local machine, you’ll be directed to the localhost, but on a server you should go to the IP address of that server.

The first time you open Sourcegraph, the page that will be displayed will be the page to setup your administrative account.

![Sourcegraph create account and login page](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-login-page.png)

You can create the account now. This account will be tied to your own instance of Sourcegraph.

Once you set up your account, you’ll be able to add repositories and set up your preferences and configuration.

## Next steps

Congratulations! You have installed Sourcegraph with Docker on your Linux machine and have created an account so that you can begin using Sourcegraph to search all of the code that is important to you.

If you have installed Sourcegraph on a Linux server rather than a local machine, you may want to secure your installation as a next step (to access Sourcegraph via `https` rather than `http`), which you can read more about through our official [Sourcegraph docs](https://docs.sourcegraph.com/admin/http_https_configuration#sourcegraph-single-instance-docker).

Once you have Sourcegraph up and running, and your code repositories available to Sourcegraph, you can check our overview video on the [three ways to search with Sourcegraph](/three-ways-to-search-code-with-sourcegraph) so that you can more effectively search your code.


Installing a self-hosted Sourcegraph test instance on Linux with Docker

Learn how to install Sourcegraph on your own machine with Docker

How to install Sourcegraph on Linux with Docker


Sourcegraph is a tool that can allow you to search all the code that is important to you, from your own local repositories, to the software you build together with a team, to all the code that is available through open source projects. You can get started using Sourcegraph by using [Sourcegraph cloud](https://sourcegraph.com/search) with your preferred web browser, or you may want to install Sourcegraph locally or on a cloud server or virtual machine.

By installing Sourcegraph on your own hardware, you’ll be able to manage your own instance of Sourcegraph, providing you with complete control over who has access to your code. Your own installation will also allow you to connect your local (or server-side) code as well as any relevant Git servers. Git servers that you can connect to include GitHub, GitHub Enterprise, GitLab, Bitbucket, AWS CodeCommit, Perforce, and more.

We’ll go through how to install Sourcegraph on your local macOS machine with Docker so that you can begin to use Sourcegraph on all of your code. 

---
**NOTE**:

Sourcegraph does not provide support for machines with the Apple M1 chip. The below guidance provides suggestions for both Intel chips and M1 chips, but only the Intel chips are supported by Sourcegraph.

---

This installation guide is appropriate for local testing and should be quick to set up. If you would like to use Sourcegraph in a production environment, you should follow our documentation on installing Sourcegraph with [Docker Compose](https://docs.sourcegraph.com/admin/install/docker-compose) on a single node, or on a [Kubernetes cluster](https://docs.sourcegraph.com/admin/install/kubernetes).

## Step 1 — Install Docker

_If you already have Docker installed, you can [skip to the next step](#step-2--install-sourcegraph)._

On a macOS machine, you can install Docker from the [Docker installation page for Mac](https://docs.docker.com/docker-for-mac/install/). You’ll need to ensure that you are installing the right version for your machine’s respective chip.

You can determine what chip you have by navigating to the Apple menu in the top left corner of your screen, selecting `About This Mac` and reviewing what is displayed next to `Chip` in the window that appears.

Once you know which is the appropriate version to install, select either `Mac with Intel chip` for any macOS machine that is on an Intel chip, or `Mac with Apple chip` for any macOS machine that has an Apple M1 chip. Then follow the guidance from the Docker installation to complete the process.

With Docker fully installed, you’ll be ready to move onto the next section.

## Step 2 — Install Sourcegraph

Depending on the chip that you have, you’ll be able to run a Docker command to install Sourcegraph and get up and running with code search on your local repositories and beyond. 

The first section is for macOS machines with [Intel chips](#on-macos-with-intel-chip), and is currently the only macOS chip supported by Sourcegraph. The second option is a suggested workflow for macOS with [Apple M1 chips](#on-an-apple-m1-chip-on-macos), though this is not supported by Sourcegraph.

### On macOS with Intel chip

On local machines with an Intel chip, you’ll be able to install Sourcegraph by running the following Docker command.

```sh
docker run --publish 7080:7080 --publish 127.0.0.1:3370:3370 \
--rm --volume ~/.sourcegraph/config:/etc/sourcegraph \
--volume ~/.sourcegraph/data:/var/opt/sourcegraph \
sourcegraph/server:3.29.0
```

This command is telling your computer to install and run Sourcegraph in port 7080 of your localhost (127.0.0.1) and is calling up the relevant files from the Docker image of Sourcegraph. It is also setting up a store for your Sourcegraph data.

Once you run the command, you’ll receive some output indicating that Sourcegraph is getting set up. Sourcegraph will be ready when you receive the output similar to the following:

```sh
✱ Sourcegraph is ready at: http://127.0.0.1:7080
```

At this point, you’ll be able to move onto the next section to verify your installation.

### On an Apple M1 chip on macOS

On a macOS machine with an Apple M1 chip, you’ll need to add an extra argument to your Docker command so that the platform does not interfere with the installation and running of Sourcegraph. Run the following command with the `--platform linux/amd64` argument as demonstrated below.

```sh
docker run \
--publish 7080:7080 --publish 127.0.0.1:3370:3370 \
--platform linux/amd64 \
--rm --volume ~/.sourcegraph/config:/etc/sourcegraph \
--volume ~/.sourcegraph/data:/var/opt/sourcegraph \
sourcegraph/server:3.30.4
```

This command is telling your computer to install and run Sourcegraph in port 7080 of your localhost (127.0.0.1) and is calling up the relevant files from the Docker image of Sourcegraph. It is also setting up a store for your Sourcegraph data.

Once you run the command, you’ll receive some output indicating that Sourcegraph is getting set up. Sourcegraph will be ready when you receive output similar to the following:

```sh
✱ Sourcegraph is ready at: http://127.0.0.1:7080
```

At this point, you’ll be able to move onto the next section to verify your installation.

## Step 3 — Verify the installation

When Sourcegraph is fully installed and ready to be used, the Sourcegraph logo will appear and you should access the URL that is indicated in the Terminal output.

![Installation complete verification on command line](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-logo-terminal.png)

Open a browser and go to the URL indicated in the output. Keep in mind that if you are using a local machine, you’ll be directed to the localhost, but on a server you should go to the IP address of that server.

The first time you open Sourcegraph, the page that will be displayed will be the page to setup your administrative account.

![Sourcegraph create account and login page](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-login-page.png)

You can create the account now. This account will be tied to your own instance of Sourcegraph.

Once you set up your account, you’ll be able to add repositories and set up your preferences and configuration.

## Next steps

Congratulations! You have installed Sourcegraph with Docker and have created an account so that you can begin using Sourcegraph to search all of the code that is important to you.

Once you have Sourcegraph up and running, and your code repositories available to Sourcegraph, you can check our overview video on the [three ways to search with Sourcegraph](/three-ways-to-search-code-with-sourcegraph) so that you can more effectively search your code.


Installing Sourcegraph to search code on a local instance with macOS and Docker

Learn how to install Sourcegraph on your Apple Mac with Docker

How to install Sourcegraph on macOS with Docker


Sourcegraph is a tool that can allow you to search all the code that is important to you, from your own local repositories, to the software you build together with a team, to all the code that is available through open source projects. You can get started using Sourcegraph by using [Sourcegraph cloud](https://sourcegraph.com/search) with your preferred web browser, or you may want to install Sourcegraph locally or on a cloud server or virtual machine.

By installing Sourcegraph on your own hardware, you’ll be able to manage your own instance of Sourcegraph, providing you with complete control over who has access to your code. Your own installation will also allow you to connect your local (or server-side) code as well as any relevant Git servers. Git servers that you can connect to include GitHub, GitHub Enterprise, GitLab, Bitbucket, AWS CodeCommit, Perforce, and more.

We’ll go through how to install Sourcegraph on your local Windows machine with Docker so that you can begin to use Sourcegraph on all of your code. 

---
**NOTE**:

Sourcegraph can only be tested on Windows 10 as data will not be retained after server restarts, due to a limitation of Docker on Windows.

---

This installation guide is appropriate for local testing and should be quick to set up. If you would like to use Sourcegraph in a production environment, you should follow our documentation on installing Sourcegraph with [Docker Compose](https://docs.sourcegraph.com/admin/install/docker-compose) on a single node, or on a [Kubernetes cluster](https://docs.sourcegraph.com/admin/install/kubernetes).

## Step 1 — Install Docker

_If you already have Docker installed, you can [skip to the next step](#step-2--install-sourcegraph)._

On a Windows machine, you can install Docker from the [Docker installation page for Windows](https://docs.docker.com/docker-for-windows/install/). Follow the guidance from the Docker installation.

With Docker fully installed, you’ll be ready to move onto the section below to install Sourcegraph. 

Please note that Sourcegraph can only be tested on Windows 10 as data will not be retained after server restarts, due to a limitation of Docker on Windows.

## Step 2 — Install Sourcegraph

Due to limitations with Docker for Windows, Sourcegraph can only be tested on Windows as data cannot persist on a Windows installation. Due to that, we won't be using the `--volume` argument in our command.

```sh
docker run --publish 7080:7080 --publish 127.0.0.1:3370:3370 `
--rm sourcegraph/server:3.29.0
```

_The above command with backtick assumes use of PowerShell. If you're using the Windows Command Prompt, substitute `^` as below._

```sh
docker run --publish 7080:7080 --publish 127.0.0.1:3370:3370 ^
--rm sourcegraph/server:3.29.0
```

This command is telling your computer to install and run Sourcegraph in port 7080 of your localhost (127.0.0.1) and is calling up the relevant files from the Docker image of Sourcegraph.

Once you run the command, you’ll receive some output indicating that Sourcegraph is getting set up. Sourcegraph will be ready when you receive output similar to the following:

```sh
✱ Sourcegraph is ready at: http://127.0.0.1:7080
```

At this point, you’ll be able to move onto the next section to verify your installation.

## Step 3 — Verify the installation

When Sourcegraph is fully installed and ready to be used, the Sourcegraph logo will appear and you should access the URL that is indicated in the Terminal output.

![Installation complete verification on command line](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-logo-terminal.png)

Open a browser and go to the URL indicated in the output. Keep in mind that if you are using a local machine, you’ll be directed to the localhost, but on a server you should go to the IP address of that server.

The first time you open Sourcegraph, the page that will be displayed will be the page to setup your administrative account.

![Sourcegraph create account and login page](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-login-page.png)

As this is a test installation, you can choose whether this page satisfies your testing needs, or continue to create a test account and explore further.

## Next steps

Congratulations! You have installed a test environment of Sourcegraph with Docker on Windows and can begin using Sourcegraph to search all of the code that is important to you.

Once you have Sourcegraph up and running, and your code repositories available to Sourcegraph, you can check our overview video on [Three ways to search code with Sourcegraph](/three-ways-to-search-code-with-sourcegraph) so that you can more effectively search your code.


Installing Sourcegraph for code search testing on Windows with Docker

Learn how to install Sourcegraph on your Windows machine with Docker

How to install Sourcegraph on Windows with Docker


Sourcegraph is a universal code search tool, allowing you to search across your own code or public open source repositories that you add to your instance. You can begin experimenting with Sourcegraph through [Sourcegraph cloud](https://sourcegraph.com/search), which is available in-browser and has millions of open source repositories indexed.

Once you know that you would like to self-host your own instance of Sourcegraph to search across your local or cloud repositories, and you want it to be suitable for a production environment, you can follow along with this tutorial that will set you up with a Sourcegraph instance on Docker Compose. This tutorial will assume *nix commands on the command line. 

If, instead, you would like to perform a quick install of Sourcegraph with Docker, which is suitable for testing environments, you can do so by following one of our tutorials for [Linux](https://learn.sourcegraph.com/how-to-install-sourcegraph-on-linux-with-docker), [cloud Linux](https://learn.sourcegraph.com/how-to-install-sourcegraph-with-docker-on-a-linux-cloud-server), [macOS](https://learn.sourcegraph.com/how-to-install-sourcegraph-on-mac-with-docker), or [Windows](https://learn.sourcegraph.com/how-to-install-sourcegraph-on-windows-with-docker).

Installing Sourcegraph into your production environment can allow you to use advanced features of Sourcegraph. You can also review our [installation documentation](https://docs.sourcegraph.com/admin/install).

## Prerequisites and estimating your setup needs

To install Sourcegraph with Docker Compose, your setup will need to meet certain requirements. We recommend following the official documentation to install [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/).

* You have [Docker](https://docs.docker.com/engine/install/) installed, and it’s v20.10.0 or above. 
* You have [Docker Compose](https://docs.docker.com/compose/install/) installed, and it’s v1.22.0 or above.
* Your machine or server has an estimated minimum number of 8 CPU cores.

Use the [resource estimator](https://docs.sourcegraph.com/admin/install/resource_estimator) to ensure that your machine meets the minimum requirements for your Sourcegraph instance needs based on the number of code repositories and number of users you are planning to set up on your instance. 

## Step 1 — Fork the reference repository

First, you will need to create a fork of the [sourcegraph/deploy-sourcegraph-docker reference repository](https://github.com/sourcegraph/deploy-sourcegraph-docker/).

You can fork the reference repository from GitHub’s user interface. Having a GitHub account is required when forking repositories that are hosted on GitHub.

To fork the repository using GitHub’s user interface, navigate to the [reference repository](https://github.com/sourcegraph/deploy-sourcegraph-docker/). On the right-hand side of the top navigation pane, you will find a **Fork** button.

![GitHub interface showing the Fork button on the Deploy Sourcegraph with Docker repo](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/fork-deploy-sourcegraph-docker-repo.png)

When you click on the **Fork** button, GitHub will create a fork of the repository for you.

With the forked repository, you can make customizations that are tailored to your organization’s needs. The original repository will remain as a source of truth when you need to make updates or upgrades to your Sourcegraph instance.


## Step 2 — Clone the forked repository

After forking the reference repository, you may want to create a directory or move to a directory on your machine or host where the fork will live. Clone the forked repository into this directory, which is called the configuration directory.

For our example, we’ll move into a temporary directory, `~/tmp`.

```sh
cd ~/tmp
```

Enter the following command on your terminal to clone your forked repository. Be sure to substitute _your username_ where we have `your-username` written out in the URL.

```sh
git clone https://github.com/your_username/deploy-sourcegraph-docker/
```

You should receive output similar to the following:

```
Cloning into 'deploy-sourcegraph-docker'...
...
Resolving deltas: 100% (4418/4418), done.
```

Once you clone the Git repository, all the relevant code lives locally on your machine or server. You now have a copy of the reference repository that you can configure to suit your needs.


## Step 3 — Add the reference repository as upstream remote

A connection to the upstream repository you forked in [Step 1](#step-1--fork-the-reference-repository) gives you the necessary connection to pull from the reference as needed. Remote repositories are versions of your project that are hosted online, in this case it is the main reference project maintained by Sourcegraph.

To set up your reference to the remote upstream repository, you’ll first need to move into the directory of your cloned repo. For our example, the path is the following, but be sure to use the path relevant to your machine and file structure. 

```sh
cd ~/tmp/deploy-sourcegraph-docker/
```

From within the `/deploy-sourcegraph-docker` directory, use the following command that passes in the URL of the `sourcegraph/deploy-sourcegraph-docker` project to set up the remote upstream. 

```sh
git remote add upstream https://github.com/sourcegraph/deploy-sourcegraph-docker
```


If everything was successful, you will be at a new line of your terminal, with no other output.

Because you have pull access, you can keep up with changes on the reference repository by pulling the main branch whenever there is an update.

## Step 4 — Install Sourcegraph on your host

Move to the configuration directory (the file path on your machine that contains the clone to the fork you created), and navigate to the Docker Compose folder.

```sh
cd ~/tmp/deploy-sourcegraph-docker/docker-compose
```

Within this directory, you can spin up the Sourcegraph instance on your host with Docker Compose. Here, `up -d` refers to starting the containers in the background and leaving them running; the `-d` flag refers to running the containers in a **d**etached mode.

```sh
sudo docker-compose up -d
```

Once you run this, you will know that your installation was successful when you receive output that generates `done` messaging, and output that notifies you that Sourcegraph is ready. This will display with your server or localhost IP address and the relevant port.


```
Sourcegraph is ready at: [an-address-and-port-created-by-your-server]
```

You can access Sourcegraph using the relevant IP address and port number. 

## Step 5 — Check that the service is healthy

After receiving the message that Sourcegraph is ready, you will need to check that the service is healthy by running the Docker process command or `docker ps` for short.

Sometimes, a service may be running but cannot respond to requests because a required step is not complete. Running a health check lets you know the actual state of the service.

```sh
docker ps
```

The instance is healthy when the `sourcegraph-frontend-0` image is running and is marked as “healthy” on your host’s terminal.

```
[your-container-id]  sourcegraph-frontend-0  "/sbin/tini -- /usr/…"  Up 20 minutes(healthy)
```

A service will be marked as healthy if it has fulfilled all the checks that it needs to run.

## Step 6 — Access Sourcegraph with a browser

Copy the IP address created by your server and access it with a web browser of your choice. The link leads to a page that lets you create an account to start using Sourcegraph.

![Sourcegraph signup landing page](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/sourcegraph-docker-compose-signup.png)

After successfully installing Sourcegraph with Docker Compose, you can [create a Sourcegraph Account](https://learn.sourcegraph.com/how-to-create-a-self-hosted-sourcegraph-account).

## Next steps

Now that you have Sourcegraph installed and you also have a Sourcegraph account, you can check out our [Sourcegraph resources](https://learn.sourcegraph.com/tags/sourcegraph) to find helpful guides on how to use Sourcegraph effectively. 

You can also learn more about Sourcegraph by reviewing our product [docs](https://docs.sourcegraph.com/).


Install self-hosted Sourcegraph for a production environment

Install a self-hosted Sourcegraph instance for a production environment to search all of your code

How to install Sourcegraph with Docker Compose


Sourcegraph is a universal code search tool, enabling you to search across both open source and your own private code repositories. Code search can help you onboard onto new codebases, contribute to open source, find bugs and error messages, understand dependency libraries, and more.

This cheat sheet style guide can help you get up to speed with Sourcegraph commands quickly. For more thorough tutorials on using Sourcegraph, refer to our [tutorials](https://learn.sourcegraph.com/tags/sourcegraph) and our [documentation](https://docs.sourcegraph.com/). 

You can use these commands on either [Sourcegraph cloud](https://sourcegraph.com/search) or your own [Sourcegraph instance](https://docs.sourcegraph.com/admin/install).

## Searching an organization’s repository

By default, Sourcegraph lets you search globally, providing you with results from all the repositories you have access to. On Sourcegraph cloud, this includes all currently indexed open source repositories. The `repo` command lets you dial down to the single repository level.

### Searching for or within a repository

The `repo` keyword lets you search a specific repository in your organization or on the web.

```
repo:[repository-path]
repo:[regular-pattern]
```

Searching with `repo:^github\.com/ORGANIZATION` will return all repositories in a given organization, where `ORGANIZATION` can be `sourcegraph`, for example.

<SourcegraphSearch query="repo:^github\.com/sourcegraph/.*" />


The `repo` keyword contextualizes the searches you perform on Sourcegraph. 

### Repository search: command chaining

When searching a repository, command chaining can be used to return more specific results depending on the expected results.

**Search for a repository that contains a file**

If you are searching for a file in a repository, use `repo.contains.file`.

```
repo:[repository-path] repo.contains.file([file-path])
```

For example, when searching for the `package.json` file in a project, this search query will return the file.


<SourcegraphSearch query="repo:^github\.com/sourcegraph/.* repo:contains.file(package.json)" />


A similar example that uses the content query to search for files is shown below.


<SourcegraphSearch query="repo:contains(file:package\.json$ content:ts)" />


This query returns repositories that contain a `package.json` file and has content written in TypeScript.


**Search for a repository that contains some content**

Suppose you are searching for some content in a repository, such as a library. Use `repo.contains.content`.

```
repo:[repo-path] repo.contains.content([content])
repo:[repo-path] repo.contains.content([regular-pattern])
```

We can search for the `mdi-react` library in Sourcegraph, for example:

<SourcegraphSearch query="repo:^github\.com/sourcegraph/.* repo:contains.content(mdi-react)" />


The above query returns repos that have `mdi-react` among its contents.

## Language-specific search

Use `lang` when searching code to narrow the scope of your search to one programming language. 

```
lang:[programming language]
```

We can search for results within the C++ or Python programming languages.


<SourcegraphSearch query="lang:c++" />

<SourcegraphSearch query="lang:python" />


By default, searches are case insensitive.

Prepending a hyphen can exclude results from a particular programming language.

```
-lang:[programming-language]
```

To exclude Java, you can perform the following search.

<SourcegraphSearch query="​​-lang:java" />

Narrowing your search scope down to specific languages can ensure that you find the code that is most relevant to your needs.

## Searching based on time periods

If you are searching for code committed before or after a time period, you will use `before` and `after`

```
before:[time-period]
after:[time-period]
```

Sometimes the time period can be literal, like `last week`, `last year`, `3 months ago`, `february 10 2021` or have actual dates in the format `dd/mm/yyyy`.

```
before:last week
after:february 10 2021
before:02/01/2019
```

To search between dates, keywords like `and` can be combined with `before` or `after` to return dates within a given period.

<SourcegraphSearch query='repo:sourcegraph type:commit after:"july 9 2021" and before:"july 10 2021"' />

Time-based search is usually used along with other search commands to further narrow down search results.

Note that `before` and `after` only work in conjunction when combined with `type:diff` or `type:commit` commands.

## Search in archived repositories

The `archived` keyword will bring up those results from repositories that have been archived.

```
archived:[yes/only]
archived:yes
archived:only
```

We can surface only archived repositories within the Sourcegraph organization with the following query.

<SourcegraphSearch query="repo:sourcegraph archived:only" />

This can help us understand past decisions made within a given codebase. 

## Case sensitive search

Use `yes` or `no` with the `case` search query to specify if the search should be case sensitive or not. By default, searches are case insensitive.

```
case:[yes/no]
case:yes
case:no
```

Suppose you would like to check to align the style of a given codebase to help you bring all function calls in Python to be consistent with the [PEP 8](https://www.python.org/dev/peps/pep-0008/) guidance. You can use Sourcegraph to understand which functions are using camelCase rather than lowercase names with underscores between words (also called snake_case).

<SourcegraphSearch query="case:yes lang:python myFunction" />


If you would like to find all declared functions that use camelCase, you can try combining this query with regular expressions.

## Searching by types

Types define the scope of code search. A search scope consists of commits, diffs, symbols, repos, paths and files. It is typically used alongside other search commands to further narrow search results.

```
type:[commit|paths|diff|symbol|repo|files]
```

Here is an example to show us time-based commits on the Sourcegraph repo.

<SourcegraphSearch query="repo:sourcegraph after:yesterday type:commit" />

A `type` scope can use the following commands, which will restrict search to the following:
* `commit` — commits to a repository
* `diff` — show [diffs](https://git-scm.com/docs/git-diff), or changes, within a repository
*`repo` — repositories available to you
* `files` — returns files 
*`symbol` — returns files that contain names or keywords in a library.

Searching by type can help you find exactly what you need in a codebase by narrowing down the scope of your search. 

## Searching commit messages matching a string

If a commit message is known, it can be helpful to use the `message` keyword to bring up relevant commits.

```
message:[commit-message]
message:[string-regex-pattern]
```

We can find all commit messages with “fix” in the `sourcegraph/sourcegraph` repository by searching the following.

<SourcegraphSearch query="repo:^github\.com/sourcegraph/sourcegraph$ type:commit message:fix" />

Note that the message keyword only works for `type:diff` or `type:commit` queries.

## Searching code by commits and diffs 

The `author` keyword returns code search results that were created by a user. This keyword only works for `type:diff` or `type:commit` queries.


```
author:[author-name]
```

Adding a hyphen in front of the `author` keyword omits code content created by a given author.

```
-author:[author-name]
```

Search for all code diffs by the Renovate app within our Sourcegraph repository.

<SourcegraphSearch query="repo:^github\.com/sourcegraph/sourcegraph$ author:renovate type:diff" />

You can also search by `committer:git-email` with the same `type` constraints.

## Return a certain number of results

Sourcegraph returns pages filled with search results. To stop searching after a given number of results are returned, use the `count` command.

```
count:[number|all]
```

For example, `count:5` would return the first 5 results of a given query.

<SourcegraphSearch query="repo:sourcegraph/learn type:commit count:5" />

The `all` option returns all results from a search.

The `count` keyword may also be used to return _more_ results, not just  _fewer_ results. This can enable you to display more than the default 500 results that are returned.

## Searching for or within forks

The `fork` keyword restricts the scope of search results to either include, exclude, or return only  forks of a given repository.

```
fork:[yes|no|only]
```

The `yes` option includes forked repositories, the `no` option omits the results from forks, and the `only` option searches only forked repositories.

One use case for searching forked repositories is looking for how users personalize open source libraries.

## Timing out searches

To set the duration before a search times out, you’ll use the `timeout` keyword. Time units that can be used include nanoseconds (`ns`), microseconds (`us` or `µs`) , milliseconds (`ms`), seconds (`s`) or minutes (`m`).

```
timeout:[time-duration-with-unit]
```

This is useful when searching many repositories at the same time to give search more time to return useful results. By default, timeout is 10 seconds, however, when using the `timeout` command, timeouts can be set to over a minute. When this scope is provided, search is given more time to complete.

<SourcegraphSearch query="timeout:40s" />

Alternatively, if you are receiving too many results, you can decrease the time of search.

## Search by repository visibility

Restricting search by codebase visibility is done with the `visibility` command. You can restrict search to public or private repositories.

This is useful if you want the results of a search to be explicitly narrowed down to repositories that are private and accessible to you or repositories that are public. 

Except when explicitly set, all searches return results from both public and private repositories accessible to you.

```
 visibility:[any|private|public]
```

When logged into Sourcegraph, you can change your context to your username and then run the following command to show all of your available private repositories.

<SourcegraphSearch query="visibility:private" />

This can allow you to search across the code that is private to only you. _Please note that searching private code on Sourcegraph cloud is currently in Public Beta._

## Further resources

To learn more about how to search effectively with Sourcegraph, you can read through our Sourcegraph search series:
* [How To Search with Sourcegraph using Literal Patterns](/how-to-search-code-with-sourcegraph-using-literal-patterns)
* [How To Search with Sourcegraph using Regular Expression Patterns](/how-to-search-with-sourcegraph-using-regular-expression-patterns)
* [How To Search with Sourcegraph using Structural Patterns](/how-to-search-with-sourcegraph-using-structural-patterns)

You can also check out [Sourcegraph product documentation](https://docs.sourcegraph.com/) and [Sourcegraph tutorials](https://learn.sourcegraph.com/tags/sourcegraph).


Getting started with Sourcegraph universal code search

A guide to help you get up to speed with Sourcegraph's commands quickly

How to search code with Sourcegraph — a cheat sheet


Sourcegraph code search is a search engine that allows you to search code in your own repositories as well as across public open source code. It supports three kinds of search patterns: literal patterns, regular expression patterns, and structural patterns. In this article, we’ll explore literal search patterns and how to use them.

Performing a literal search is useful when you know the exact string that you’re looking for in a code base, like a particular function or variable name. You can find all occurrences of the name across multiple repositories by using your query as a literal pattern. It’s also useful for finding textual content — like error messages or comments — in the code.

By default, all search queries on Sourcegraph are treated as literal patterns. We’ll discuss a few use cases to find useful results with Sourcegraph.

## Finding function calls and definitions

As a developer, there are many times you may need to learn a new codebase: you may need to understand how best to use a new package, may need to be onboarded into an existing project, or may want to learn best practices from tried and tested software. A productive way to become familiar with a codebase is through selecting a function and understanding how it’s used throughout the code and in what contexts.

For example, if you’re learning how the Linux kernel works, one of the topics that you may want to understand is how Linux uses linked lists. Because linked lists are used throughout the Linux kernel and in driver code, they are a foundational starting point to familiarize yourself with the codebase.

The linked list data structure in Linux is called `list_head`. We can find all instances of the `list_head` structure by searching for it directly:

<SourcegraphSearch query="list_head"/>

As you review the results, you may notice that there are some common functions that are frequently used together with linked lists. One of these functions is `list_add_tail`. To explore further and find all instances of `list_add_tail`, we can start a new search for that specific function:

<SourcegraphSearch query="list_add_tail"/>

Literal search patterns can be used to find more than just functions or variables. They can also be used to find longer pieces of text, like error messages, as we’ll explore in the next section.

## Finding error messages

Literal search can help you find where a particular piece of text occurs within code. For example, if you’re seeing an error message while debugging, it can be helpful to find where that message is defined in the code to get a better idea of what is causing it. You can search for an exact match by copying the error into your search.

Let’s try an example. React is a framework used by many web apps, and its error messages are sometimes hard to debug. When a React component throws an error, it produces an error message like, `React caught an error thrown by Component`. When you get an error message like that, it isn’t always clear what is going on. To learn more about the source of the error, you can search for the error message itself:

<SourcegraphSearch query="React caught an error thrown"/>

By finding where an error message is defined, you can start to understand what conditions will cause this error. In this case, it happens when React catches an error that happened during the rendering phase in one of your components.

This kind of search also gives you an understanding of the inner workings of the codebase, and that can be really helpful to get a better mental model of how it works.

## Finding sequences of words

By default, when searching for literal patterns in Sourcegraph, the entire query will be searched, even if the pattern consists of multiple worlds. You should not put your query in quotes: we’ll go into more detail about this now.

Unlike a web search engine, if you search for two or more words on Sourcegraph, like `const counter`, then you’ll only get results for `const` immediately followed by `counter`, as in the example below.

<SourcegraphSearch query="const counter"/>

Returning to our example in the Linux kernel, we can narrow down our search for `list_head` to only the cases where it’s used as a simple structure ([`struct`][struct]), by searching specifically for the `struct list_head` pattern:

<SourcegraphSearch query="struct list_head"/>

If you want to find all instances of those two words appearing in the same file but not necessarily in sequence, then you can use the `and` operator, or you can switch to regular expression mode.

To use the `and` operator, add it to your search. The following query will find occurrences of `list_head` and `list_add_tail` when they are present anywhere in the same file.

<SourcegraphSearch query="list_head and list_add_tail"/>

If you try one of these examples with quotes around the search query, like `"const counter"`, you’ll notice that you get no results. This is because the quote characters are interpreted literally, so Sourcegraph will search for textual data that includes those quote characters.

There are cases where searching for quote characters is useful. We’ll explore that in the next section.

## Finding quoted string constants

Because quote characters are treated like any other character when you’re in literal pattern mode, you can search for quoted strings by including the quotes in your search.

For example, the quoted string `"ENOENT"` represents the error when a file is not found in Linux, and it’s found in many codebases:

<SourcegraphSearch query='"ENOENT"'/>

By including the quotes in the search query, you can compare this search with the same string, but without quotes. You’ll receive other results, where the string isn’t necessarily in quotes.

<SourcegraphSearch query='ENOENT'/>

## Learn more

We’ve explored how to use Sourcegraph to search for literal patterns like function names, variables names, error messages, and strings. You can learn more about Sourcegraph search syntax in the [documentation].

Literal search patterns are a useful starting point, but often you need to search for patterns in your code that require more flexibility. Sourcegraph offers two other types of patterns: [regular expressions] and [structural search].

To go beyond literal patterns, you can use regular expressions or structural search patterns.

**Related links:**

- [Sourcegraph search query documentation][documentation]
- [Sourcegraph regular expression search][documentation]
- [Sourcegraph structural search][structural search]

[struct]: https://en.wikipedia.org/wiki/Struct_(C_programming_language)
[documentation]: https://docs.sourcegraph.com/code_search/reference/queries
[regular expressions]: https://docs.sourcegraph.com/code_search/reference/queries#regular-expression-search
[structural search]: /how-to-search-with-sourcegraph-using-structural-patterns


Searching code with Sourcegraph using literal search

Learn how to use literal search patterns to search code on Sourcegraph.

How to search code with Sourcegraph using literal patterns


Sourcegraph lets you search code across repositories, supporting three kinds of search patterns: literal patterns, regular expression patterns, and structural patterns. In this article, we’ll take a look at regular expressions patterns and how to use them in Sourcegraph.

Regular expressions, often shortened as _regex_, help you find code that matches a pattern (including classes of characters like letters, numbers and whitespace), and can restrict the results to anchors like the start of a line, the end of a line, or word boundary.

## Enabling regular expression search on Sourcegraph

Start searching with regular expression patterns by toggling the dot asterisk (`.*`) button towards the right-hand side of the search box. When you mouse over it you’ll receive a tooltip that reads `Enable regular expression`.

<GifLikeVideo url="https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/enable-regex.mp4"/>

Once it is highlighted, you're ready to search with regular expressions.

## Finding a pattern

Regular expressions are useful when you're looking for any strings that match a particular pattern. A common pattern in CSS is the RGB hex color code, like #6495ED (cornflower blue) or #663399 (Rebecca purple).

To match RGB hex color codes, we can write a regular expression that has three parts:

- A hash symbol (`#`)
- A character class for hexadecimal characters: `[0-9a-f]`
- A repetition operator, indicating that we're looking for 6 characters that match the above character class: `{6}`

Combining these parts into one regular expression, we can use this pattern in a Sourcegraph search. To make the results more relevant, we can add the `lang:css` filter so that we target only CSS files.

<SourcegraphSearch query="#[0-9a-f]{6} lang:css" patternType="regexp"/>

Regular expressions are useful for finding patterns like this, where certain classes of characters are repeated a certain number of times.

## Finding a set of function calls

One use case for regular expression search is when you are trying to find examples of file system function calls. You may be interested in functions that read or write files: `readFile` and `writeFile`. While you could search for them individually, it can be useful to perform one search that includes results for both functions.

`readFile` and `writeFile` have a pattern in common: they both end in `File`. We can write a regular expression that expresses this pattern like so:

<SourcegraphSearch query="(read|write)File" patternType="regexp"/>

The above search query uses the regular expression syntax of a pipe (`|`) character, which signifies “or”. We can read the query as a search for “`read` or `write`” followed by `File`.

If you would like to narrow down the scope of the search, you can modify this pattern further. If you would like to specify that you would like to use the file system prefix of `fs`, as in `fs.readFile` or `fs.writeFile`, you can add that prefix to the search. Because the `.` dot character notation has a special regex meaning (it will match all characters), we will want to escape the dot with a backslash (`\`).

<SourcegraphSearch query="fs\.(read|write)File" patternType="regexp"/>

Regular expressions are also useful if you’re looking for a variable that can contain a mix of alphabetic and numeric characters, like `id1`, `id2`, `id3` and so forth. To narrow down the results, we can add the `type:symbol` filter.

<SourcegraphSearch query="id\d+ type:symbol" patternType="regexp"/>

In this case `\d+` matches one or more digits.

## Using spaces in regular expression patterns

It’s common to be looking for a pattern with two keywords, separated by any other text in between.

When using regular expressions in Sourcegraph, the space character matches any characters between keywords. So if you search for two words in regular expressions mode, like `auth service`, you’ll get results where `auth` and `service` are found on the same line, and any other number of characters (not limited to spaces) may be in between.

<SourcegraphSearch query="auth service" patternType="regexp"/>

When you use spaces in regular expressions in Sourcegraph, the space character is automatically interpreted as replaced by the `.*` pattern. This pattern matches any number of characters on the same line (including none). When you’re looking for two words appearing together in a code base, but not necessarily right next to each other, regular expression mode is a useful way to find relevant results.

## Finding whole words using word boundaries

By default, Sourcegraph finds all occurrences of your search pattern even when it occurs inside of a longer word. Sometimes when you’re searching for a pattern like `count`, you’re only interested in functions or variables called `count` and not `counter` or `countId` or `countItems`. In those cases, you should specify that you’re looking for an exact keyword. You can do this with the regular expression `\b`, which stands for _word boundary_.

<SourcegraphSearch query="\bcount\b" patternType="regexp"/>

We can use this to improve the search from our earlier example. You may have noticed that the search for `readFile` and `writeFile` returned other functions that started with those patterns, like `readFileAsync`. By using a word boundary, we can restrict the search to only match the exact function name.

<SourcegraphSearch query="(read|write)File\b" patternType="regexp"/>

In the above search we’re adding `\b` at the end of the query, but not at the beginning. This way, we can express that we’re looking for matches that end with this pattern, but may have an alternate prefix.

## Finding patterns at the start of a line

We’ve looked at ways to find matches that are located anywhere in a given line of code. What if you want to narrow down your search to find only the instances when the word is located at the start of the line?

You can use the line start character, `^`, and the line end character, `$`, to anchor your search. For example, here is a search that matches the word `let` when it occurs at the start of the line.

<SourcegraphSearch query="^let" patternType="regexp"/>

This won’t match lines where there’s anything before `let` on the line. That means if there’s whitespace at the beginning of the line, like tabs or spaces for indentation, then that line won’t be considered matches. Since indentation is common in code, you may want to modify the search to include results where `let` can be optionally preceded by any amount of whitespace.

This is where the `\s*` pattern is useful; it matches any number of whitespace characters (zero or more). By adding it in front of `let`, you can now include all results where the line has indentation whitespace.

<SourcegraphSearch query="^\s*let" patternType="regexp"/>

## Learn more

Regular expressions are a powerful syntax for searching code, and in this tutorial we’ve only covered some fundamental features. Sourcegraph uses the RE2 style of regular expressions, which you can learn more about by reading the [RE2 documentation](https://github.com/google/re2/wiki/Syntax).

When you’re looking for nested structures in your code, like matching brackets, argument lists, or if-then statements, then structural search can be helpful. Learn about structural search in "[How to search with Sourcegraph using structural patterns](how-to-search-with-sourcegraph-using-structural-patterns)."


Using RegEx with Sourcegraph

Learn how to use regular expression search patterns to search code on Sourcegraph.

How to search with Sourcegraph using regular expression patterns


Structural search helps you search code for syntactical code patterns like function calls, arguments, `if`...`else` statements, and `try`...`catch` statements. It's useful for finding nested and recursive patterns as well as multi-line blocks of code.

Structural search patterns are one of the three search patterns supported by Sourcegraph, along with literal patterns and regular expressions. They're different from regular expressions because they take into account the syntax of code, like balanced brackets, quoted strings, and delimiters.

## Enabling structural search on Sourcegraph

Enable structural search by clicking the icon of two square brackets (`[]`) to the right of the search box:

<GifLikeVideo url="https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/enable-structural-search.mp4"/>

Once structural search is enabled, the icon will be highlighted and you can begin performing structural searches.

## Finding function calls

Suppose we're debugging a program's error output and trying to figure out where that output is coming from in the code. We want to find calls to the `fprintf` function that writes to the standard error stream (`stderr`), which look like this:

```c
fprintf(stderr, "%s", message)
```

If we're looking only for error output, we want to match all other instances where `stderr` is the first argument of the call.

This is a situation where structural search can help:

<SourcegraphSearch query="fprintf(stderr, ...) lang:c repo:^github\.com/torvalds/linux$ " patternType="structural" />

In this example, we're using a placeholder, `...`, for the remaining arguments. This ellipses placeholder is called a "hole" in the pattern. Structural search syntax uses "holes" as placeholders for syntactic structures. In this case, the placeholder will match the remaining function arguments.

## Matching multiple function arguments

The above example gave us results that use `stderr`, but we may want to narrow down our search further. For example, we may want to match only `fprintf` calls where the final argument is `err`. We can add `err` to our search query to match it in the position of the last argument:

<SourcegraphSearch query="fprintf(stderr, ..., err) lang:c repo:^github\.com/torvalds/linux$ " patternType="structural" />

The above query matches `fprintf` calls where the first argument is `stderr` and the last argument is `err`. The `...` hole will match any number of arguments in between, and that's particularly useful for a function like `fprintf`, which accepts a variable number of arguments.

## Using multiple holes

You can use more than one `...` hole in a search. If we want to find an exact match for the second argument to `fprintf`, but accept any other arguments, we could use a hole in both the first and last argument position:

<SourcegraphSearch query='fprintf(..., "%s", ...) lang:c repo:^github\.com/torvalds/linux$' patternType="structural" />

The second argument to `fprintf` is expected to be a format string. In this above example, we'll find matches where the second argument matches the string `"%s"` exactly.

## Matching holes within strings

Structural search can interpret quote-delimited strings, too. Using the `...` hole within a string, we can match partial string literals in the code. For example, we can expand our previous search to match any format strings that start with `ERROR:`

<SourcegraphSearch query='fprintf(..., "ERROR: ...", ...) lang:c repo:^github\.com/torvalds/linux$' patternType="structural" />

In the above example, we're using three `...` holes:

- The first one accepts initial arguments
- The second one, within the string, accepts any string content that comes after the "Error:" portion of the string
- The third one accepts any final arguments.

As a whole, this search pattern helps us find `fprintf` calls that match this particular `"Error: ..."` pattern that we're looking for.

## Matching part of an expression

The `...` placeholder can also match partial content between brackets, like part of an expression.

Suppose we're investigating a bug that only happens when an array, `parts`, is empty. In the following example, we're looking for `if` statements where the condition starts with a check for whether the array is empty:

<SourcegraphSearch query="if (!parts.length && ...) { ... } lang:javascript repo:^github\.com/google/.* count:all" patternType="structural" />

The above example will match `if` statements with any additional sub-expressions that follow the `&&` operator.

In the results, we'll find code blocks that get executed when that particular array is empty, which might bring us closer to finding the cause of the bug that we're investigating.

## Finding blocks of code in brackets

Balanced bracket matching works with round brackets or parentheses, `()`, square brackets, `[]`, and curly brackets or braces `{}`.

By using curly brackets in a structural search pattern, you can match entire code blocks.

Suppose that you're working on improving a Java codebase, and you want to clean up the code's `try`...`catch`...`finally` statements. In Java, an empty `catch` clause is allowed, but it often represents an opportunity to omit the clause entirely or to refactor it.

We can construct a structural search pattern to find empty `catch` clauses that can be improved. In this case, we'll use the hole placeholder inside of curly brackets to match code blocks, but we'll deliberately keep the `catch` clause empty in order to find only the empty blocks there.

<SourcegraphSearch query="try {...} catch (...) { } finally {...} lang:java repo:^github\.com/elastic/elasticsearch$" patternType="structural" />

You can use curly brackets in structural search to match other types of code blocks as well, like `for` loops, `switch` statements, and object definitions.

## Learn more about structural search

We've discussed a few examples of structural search patterns in this article, but there are more features available in the syntax that we haven't covered. To learn more, visit the [Structural search reference](https://docs.sourcegraph.com/code_search/reference/structural) in the Sourcegraph documentation.

If you're curious about where Sourcegraph's structural search syntax originates, and want to learn more about the concept of structural search in general, you can learn more by visiting the [Comby website](https://comby.dev/), a tool that can both search and modify code. Sourcegraph's structural search syntax is a variant of the syntax supported by Comby.

## Other ways to search with Sourcegraph

While structural search is helpful for certain types of searches, there are cases where it's more straightforward to express what you're looking for as a regular expression. Learn more about searching with regular expressions in [How to search with Sourcegraph with regular expression patterns](/how-to-search-with-sourcegraph-using-regular-expression-patterns).

If you're not looking for a pattern but an exact match, then a literal search may be more straightforward. Learn about literal search patterns in [How to Search with Sourcegraph with literal patterns](/how-to-search-code-with-sourcegraph-using-literal-patterns).


Structural code search with Sourcegraph

Learn how to use structural search patterns to search code on Sourcegraph.

How to search with Sourcegraph using structural patterns


The staging area in Git is a state that files can be in before being committed to a repository. This tutorial will explain how to add and remove files from the staging area.

## Understanding `git stage`

Git’s staging area allows you to be selective in the changes you want to include in a commit. Sometimes, you may want to commit every change in your working directory to the repository. In other cases, you may want to include some changes in your commit and exclude others. It can be useful to exclude changes if they’re still a work in progress or if they’re unrelated to your current work.

Adding files to the staging area is also referred to as “staging changes” (as in: “I will stage my changes”). Removing files from the staging area is also referred to as “_unstaging_ changes” (as in: “I unstaged these changes”).

The staging area is sometimes called the “staging index” or just “index.” Some Git commands use the term “index” in their output, and it’s also sometimes used in Git documentation. In this usage, “index” is synonymous with “staging area.”

This guide will explore a few different ways that you can stage and unstage files. It will discuss several Git commands that operate on the staging area:

- `git add`
- `git restore`
- `git rm`
- `git mv`
- `git reset`

With these above commands, you’ll be able to stage and unstage changes by file, directory, or pattern.

## Staging files by name

To stage a modified file, use the `git add` command followed by a filename as the argument.

For example, to add a modified file named `license.txt`, run `git add` with the name of the file.

```sh
git add license.txt
```

While the command is called `git add`, note that this use of the word “add” doesn’t only refer to adding new files to the repository. It refers to adding any changed files to the staging area. The staging area can contain created, deleted, or modified files. You can use `git add` on a deleted file, for example.

You can list multiple filenames as arguments to `git add` to stage them all in one step. For example, to stage a set of files named `first.txt`, `second.txt`, and `third.txt`, you can run the following `git add` command.

```sh
git add first.txt second.txt third.txt
```

The above is equivalent to running `git add` on each one individually, as follows.

```sh
git add first.txt
git add second.txt
git add third.txt
```

You can stage a file that is deep in the directory structure by providing its entire path. For example, to stage a file located at `static/pages/docs/index.html`, you can provide that full path to `git add`.

```sh
git add static/pages/docs/index.html
```

The argument to `git add` is always interpreted as relative to the current directory. This means that as an alternative to the above deeply nested path, you can switch to the file’s directory first and then use `git add` on the file name directly. Here’s how you can do this by changing the current directory with `cd` and then staging `index.html` from there:

```sh
cd static/pages/docs
git add index.html
```

By using relative file paths in this way, you can stage changes from any directory in the repository tree.

## Staging directories

Similarly to staging a file, you can stage a directory by providing its path to the `git add` command. When staging a directory, all changed files within all subdirectories will be added. In other words, changes are added recursively. This is useful when you have many files that you intend to commit, all located within a particular directory of the project.

For example, to add all changes in the `docs` directory, provide the directory name to the `git add` command.

```sh
git add docs
```

Similar to staging files, you can specify multiple directories in the same command by listing them. The following example shows how to stage two directories: `docs` and `assets`.

```sh
git add docs assets
```

After running the above command, all changes contained within these two directories will be staged.

## Staging all changes

When you don’t need to select specific files or directories for a commit, you can stage all changes at once. To do that, run `git add` with the `-A` flag (or its synonym, `-all`). No other arguments are necessary when using this flag.

```sh
git add -A
```

This will stage all changes in the repository directory and all subdirectories. It will include all files that are modified, created, or deleted.

`git add -A` is not affected by the current directory. You can run it from within any subdirectory of your project, and it will apply to the entire repository.

## Staging an empty directory

Git repositories cannot contain empty directories. This means that if you create an empty directory in your project and attempt to stage it, it won’t be added to the staging area. This is because Git is only capable of tracking files and is unable to track a directory if there are no files inside. It’s a limitation of how Git represents files internally.

Empty directories can often be useful as temporary storage areas, for example, or as locations for build output. A common workaround to include an empty directory in a Git repository is to put a placeholder file inside so that it’s not truly empty. By convention, this placeholder is usually named `.gitkeep`. 

You can get a sense of how common this convention is by performing a Sourcegraph cloud search to find the presence of files named `.gitkeep` in many popular open source repositories, as demonstrated by the following search query.

<SourcegraphSearch query="file:.gitkeep"/>

If you would like to leverage this method for adding directories to your staging area like the repos that were revealed in the above query, you can also initialize a directory with `.gitkeep`.

Suppose you have an empty directory named `output` that you want to add to a repository. You can first create a placeholder file named `.gitkeep` within that directory by using the [`touch`](<https://en.wikipedia.org/wiki/Touch_(command)>) command in the terminal, which creates a blank file. Then, you can use the `git add` command to stage the directory.

```sh
touch output/.gitkeep
git add output
```

This will stage the `output` directory, which is empty except for the placeholder file, to be committed to the repository.

## Staging using a pattern

If you want to stage all files that match a pattern, like all files that end in the `.py` extension, you can use `git add` with a [glob pattern](<https://en.wikipedia.org/wiki/Glob_(programming)>).

Glob patterns use the star symbol (`*`) as a wildcard to match file names. For example, to stage all files with a `.py` extension in the current directory, you can provide the following pattern to `git add`:

```sh
git add *.py
```

The double star pattern (`**`) is a wildcard that matches any subdirectories in a file’s path. For example, to recursively stage all files named `index.js` in all subdirectories of the project, you can run `git add` with the following pattern.

```sh
git add **/index.js
```

This will find all files named `index.js`, regardless of their subdirectory, and stage them.

The above two patterns can be combined. For example, you can run the following command to stage all files ending in the `.py` extension in all subdirectories.

```sh
git add **/*.py
```

The double star (`**`) pattern will search across all subdirectories recursively and the single star (`*`) pattern will match all filenames with a `.py` extension in the project.

## Staging the deletion of a file

The `git rm` command deletes a file and then stages it. You can think of `git rm` as a replacement for two steps that can otherwise be done independently:

1. Delete the file, which is equivalent to running the `rm` terminal command on the file.
2. Add the deleted file to the staging area, which is equivalent to running `git add` with the path of the deleted file.

Like the `git add` command, `git rm` can be used with files, directories, or patterns as arguments.

For example, to remove and stage a file named `license.txt`, you can run `git rm` as follows.

```sh
git rm license.txt
```

The `license.txt` file will now be in the staging area as a deleted file.

If you’ve already deleted a file by some other means and want to stage it as a deleted file, you don’t need to use `git rm`. You can use `git add` to stage it since you only need to perform the second step of the process.

## Staging a renamed or moved file

It’s a common occurrence to rename or move a file to a different directory in the repository. In Git, renaming a file is analogous to moving it to a new file name. In either case, Git will initially interpret the change as two distinct changes:

1. The deletion of the original file.
2. The creation of a file with a new name or in a new location in the repository.

To stage a moved or renamed file, you have to stage both of these changes. You could do this manually by running `git add` on both file names, or you can use the `git mv` command.

The `git mv` command renames or moves files and also stages the change in one step. It takes two arguments: a source and a destination.

For example, to rename a file named `todo.txt` to `done.txt`, you can run `git mv` with the original name and new name as arguments.

```sh
git mv todo.txt done.txt
```

This will perform three tasks in one command:

1. Rename the file named `todo.txt` to `done.txt` in the current directory.
2. Stage `todo.txt` as a deleted file.
3. Stage `done.txt` as a newly created file.

After both changes related to a moved or renamed file are staged, Git will identify that it’s the same file under a different path. From that point, it will appear with the label `renamed` in the output of `git status`.

## Unstaging a change

We’ve explored a variety of ways to add changes to the staging area. Removing changes from the staging area can occasionally be useful, as well.

Unstaging changes can help when you’ve changed your mind about what you want to commit, or you’ve staged some changes unintentionally.

The `git restore --staged` command allows you to unstage changes and remove them from the staging area. You can think of it as the opposite of the `git add` command.

It’s necessary to include the `--staged` flag to indicate that you want to remove staged changes. If you run `git restore` without that flag, it will instead discard changes in your working directory.

Like `git add`, `git restore --staged` takes a file name as an argument. For example, suppose you previously staged a file named `README.md` using `git add`.

```sh
git add README.md
```

To unstage this file, use `git restore --staged` with the same file name.

```sh
git restore --staged README.md
```

The file’s changes will remain in the working directory, but the file will no longer be present in the staging area.

You can also provide a directory name to `git restore --staged`. This will remove all files within that directory and its subdirectories from the staging area.

## Unstaging all changes

To start the staging process over from the beginning, you can unstage all changes in one command.

The `git reset` command removes all changes from the staging area.

```sh
git reset
```

After running the above command, all changes will be unstaged but will remain in the working directory. The output gives you a summary of those changes, as in the example below.

```
Unstaged changes after reset:
M       index.html
D       script.js
D       style.css
```

From here, you can start staging changes again.

## Learn more

In this guide, we took a deep dive into different ways to stage changes in Git and to unstage them.

To learn more about using Git to create commits, read [How to commit code with the Git command-line-interface](/how-to-commit-code-with-the-git-command-line-interface).

Check out our other [Git tutorials](/tags/git) or visit the [Sourcegraph Learn home page](/) for more educational resources.


Learn how to add and remove changes from the Git staging area.

How to stage and unstage files in Git


When encountering a `SyntaxError` in Javascript, the interpreter got to a point in your program where it didn't understand the code. In other words, the token or part of the code that got the interpreter stuck did not register as valid syntax.

The `SyntaxError: missing } after function body` error is thrown by the JavaScript interpreter when it encounters a syntax error while creating a function. Most of the time, this is because the function's closing curly bracket (`}`), a block statement (conditional block for example) closing curly bracket, or some curly brackets or parentheses are missing or not in the correct order.

In this tutorial, we will help you figure out how to solve this problem.

## Reproducing the error

To demonstrate the error, let us first reproduce it. The following are two examples where the error can occur.

Let's consider this `coffee` function:

```javascript
function coffee(){
  /* Script that makes a cup of cappuccino
   without parameters. */

```

Observe that we did not close the function body with a curly bracket; this is what is causing the error. The interpreter is extremely strict, so it expects anything opened with curly brackets or parentheses to be closed.

In the example, the interpreter failed to find the expected closing bracket so it returns an error:

```
Uncaught SyntaxError: missing } after function body 4:0
note: { opened at line 1, column 16
```

In a short program like the one above, it may appear clear that a curly bracket is missing, but as code increases in complexity with many nested statements, it can be more difficult to find the error in your code prior to running it. 

Consider the following example:

```javascript
function coffe(water){
    if(water.isHot){
        /* Make a cup of cappuccino
        if water is hot*/
}

```

When you run the above, you'll receive the following output.

```
Uncaught SyntaxError: missing } after function body 6:0
note: { opened at line 1, column 27
```

The curly bracket at the end of our example program — that returned an error message — is considered to be closing the nested `if(water.isHot)` conditional block. The interpreter follows the **l**ast-**i**n-**f**irst-**o**ut (LIFO) order: the last closed curly bracket in the example above closes the last opened curly bracket, which is the conditional block statement. This version of the program makes the purpose of the single closed curly bracket clearer.

```javascript
function coffe(water){
    if(water.isHot){
        /* Make a cup of cappuccino
        if water is got*/
    }
/* missing "}" here */
```

This is what causes the error.

## Ensure that block statements are closed

JavaScript error messages tend to be helpful for debugging, so always try to read them for more information. In the error messages, you'll receive the line number where the error occurred in the output.

```
Uncaught SyntaxError: missing } after function body 4:0
note: { opened at line 1, column 16
```

In the example above, the line where the error occurred is line 4. Try to parse your code from that line and figure out which curly bracket closes which statement. Alternately, you can start debugging from the first line of the function where the error occurred.

## First close, then write code

A recommended practice that will help you avoid this kind of error when writing code is, when opening a block statement — such as a function or some parentheses — try to always open and close the body first, then write your code inside it. Using this approach, the sample code above would start out like the following.

```javascript
function coffee() {}
```

By taking this approach, you can avoid forgetting or missing the closing brackets.

## Format code with indentation

Formatting your code using indentation or spaces is another way to locate errors. By doing this, you will be able to visualize the code more readily and find the error faster.

IDEs (code editors) have extensions that can help you do the formatting automatically. One example of such an extension is [Prettier](https://prettier.io/). There is the [Bracket Pair Colorizer](https://marketplace.visualstudio.com/items?itemName=CoenraadS.bracket-pair-colorizer-2) extension, which colorizes each pair of matching brackets with the same color so you can identify them and avoid errors.

## Learn more

Read this official [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Missing_curly_after_function_body) about this error.

<SourcegraphSearch query="SyntaxError: missing } after function body" patternType="literal"/>

Check out more Sourcegraph Learn tutorials on [JavaScript](https://learn.sourcegraph.com/tags/javascript).

SyntaxError missing } after function body in JavaScript error handling

Learn how to error handle JavaScript SyntaxError missing } after function body

How to troubleshoot JavaScript SyntaxError missing } after function body


In Java, to access an element in an array you use an index. However, if that index does not exist in the array, you'll get the following exception.

```java
Exception in thread "main" java.lang.ArrayIndexOutOfBoundsException: Index 7 out of bounds for length 7
```

Arrays in Java are zero-based, which means the first position of an array is at index `0` and the last index is the length of the array minus one. So a valid index is any value between `0` and the length of the array. All other values will lead to an `ArrayIndexOutOfBoundsException`.

## Reproducing the error

Let's write a small program called `NumberPrinter.java` to understand when the exception occurs.

```java
import java.util.Scanner;

public class NumberPrinter {
    public static void main(String[] args) {
        int numbers[] = new int[]{7,6,5,4,3,2,1};

        System.out.print(
            "There are " + numbers.length + 
            " numbers in the array. How many numbers should be printed ? "
            );
        Scanner scanner = new Scanner(System.in);

        int value = scanner.nextInt();

        for (int index = 0; index < value; index++) {
            System.out.println(
                "Index " + index +" has value "+ numbers[index]
                );
        }
        System.out.println(
            "Printed " + value + " numbers out of " + numbers.length
            );
    }
}
```
The program initializes the `numbers[]` array with 7 integers and then asks the user how many values from the array should be printed. 

If the user enters a valid number, then the program enters a `for` loop which will increase the index from 0 by one and print the number at that index until the index is larger than the user-provided number.

Below is the output of our program printing out all the numbers after we entered the value `7`. Notice that the index starts at 0 and ends at 6 (the length of the array minus one).

```
There are 7 numbers in the array. How many numbers should be printed ? 7
Index 0 has value 7
Index 1 has value 6
Index 2 has value 5
Index 3 has value 4
Index 4 has value 3
Index 5 has value 2
Index 6 has value 1
Printed 7 numbers out of 7
```

If, instead, the user enters a value outside of the array, such as `8`, our program will print all the numbers up until it tries to print the number at index `7`. At this point, it will fail with `ArrayIndexArrayIndexOutOfBoundsException`.

```
There are 7 numbers in the array. How many numbers should be printed ? 8
Index 0 has value 7
Index 1 has value 6
Index 2 has value 5
Index 3 has value 4
Index 4 has value 3
Index 5 has value 2
Index 6 has value 1
Exception in thread "main" java.lang.ArrayIndexOutOfBoundsException: Index 7 out of bounds for length 7
	at NumberPrinter.main(NumberPrinter.java:13)
```

Our program failed because the index `8` value is outside the "boundaries" of our `numbers[]` array. The boundary for our array restricts the value of the index according to the following criteria:

* The index value should be greater than or equal to `0`.
* The index value cannot be larger than the length of the array. In our example, the index value cannot be larger than `7`.

Regardless of the array type in Java, the index value must adhere to the above restrictions. 

Let's go over how we can ensure that the index value is always valid.

## Check that the user-provided value is within the array boundaries

By using flow control and `if`-`else` statements, we can check that the value provided by the user adheres to the index value criteria discussed above.

```java
import java.util.Scanner;

public class NumberPrinter {
    public static void main(String[] args) {
        int numbers[] = new int[]{7, 6, 5, 4, 3, 2, 1};

        System.out.print(
            "There are " + numbers.length + 
            " numbers in the array. How many numbers should be printed ? "
            );
        Scanner scanner = new Scanner(System.in);

        int value = scanner.nextInt();
        if (value < 0) {
            System.out.println(
                "Only positive values are allowed!"
                );
            System.exit(1);
        } else if (value > numbers.length) {
            System.out.println(
                "The given value of " + value + 
                " is too large! Value has to be less than or equal to " + 
                numbers.length
                );
            System.exit(1);
        }

        for (int index = 0; index < value; index++) {
            System.out.println(
                "Index " + index + " has value " + 
                numbers[index]
                );
        }
        System.out.println(
            "Printed " + value + 
            " numbers out of " + numbers.length
            );
    }
}
```

In the code above, before we print the amount of values the user opted to be printed, we perform some validation. 

We first check that the value adheres to the first index value restriction, which is "The index value should be greater than or equal to 0". If the value doesn't adhere to this restriction, we print out a message telling the user that we only accept positive values.

If the value is positive, we then check that the value isn't too large by comparing the value to the length of the `numbers[]` array, since the second restriction states that "The index value cannot be larger than the length of the array." Once again, if the value doesn't adhere to this restriction, we print out an informative message to the user.

In the output below, we are given the result of a user entering the invalid values of first `-1` and then `8`.

```
There are 7 numbers in the array. How many numbers should be printed ? -1
Only positive values are allowed!
```

```
There are 7 numbers in the array. How many numbers should be printed ? 8
The given value of 8 is too large! Value has to be less than or equal to 7
```

These two user feedback strings are loaded into the `System.out.println()` methods within the `if` and `else if` statements, respectively. 

You could further iterate on this solution so that the program does not quit following the user inputting a value that is out of bounds by enclosing the program in a loop. 

## Pick the lowest value between the user value and the array size

We can take the solution above further to solve for these user-input concerns by translating all inputs to fit within our parameters.

First, we will use `Math.abs()`, which returns the absolute value of a given argument, to take care of the first restriction since it will force any value given by the user to always be positive.

With regard to the second restriction, if we say that when a user inputs a number that is larger than the length of our array, we can then take that to mean that the user wants all the numbers to be printed. We can accomplish that by taking the smallest value between the user given input and the length of the array.

Ultimately, we prefer the lower value, be it the user given value or the length of the array. In the program below this approach is implemented.

```java
import java.util.Scanner;

public class NumberPrinter {
    public static void main(String[] args) {
        int numbers[] = new int[]{7,6,5,4,3,2,1};

        System.out.print(
            "There are " + numbers.length + 
            " numbers in the array. How many numbers should be printed ? "
            );
        Scanner scanner = new Scanner(System.in);

        int userVal = Math.abs(scanner.nextInt());

        int value = Math.min(userVal, numbers.length);

        for (int index = 0; index < value; index++) {
            System.out.println(numbers[index]);
        }
        System.out.println(
            "Printed " + value + " numbers out of " + 
            numbers.length
            );
    }
}
```

Below is the output of the above program for if a user enters the value of `999` or `-1`, respectively.

```
There are 7 numbers in the array. How many numbers should be printed ? 999
Index 0 has value 7
Index 1 has value 6
Index 2 has value 5
Index 3 has value 4
Index 4 has value 3
Index 5 has value 2
Index 6 has value 1
Printed 7 numbers out of 7
```

```
There are 7 numbers in the array. How many numbers should be printed ? -1
Index 0 has value 7
Printed 1 numbers out of 7
```

Now, whether the user gives the program negative numbers or large numbers outside of the array, it doesn't fail or throw `ArrayIndexOutOfBoundsException` since our program is resillient to invalid index numbers.

## Learn more

Search across open source Java repositories that have the `ArrayIndexOutOfBoundsException` to understand the message more. Through this search, you will uncover some ways that developers have caught this exception. 

<SourcegraphSearch query="ArrayIndexOutOfBoundsException lang:java" patternType="literal"/>

Check out more Sourcegraph Learn tutorials on [Java](https://learn.sourcegraph.com/tags/java).



ArrayIndexOutOfBoundsException in Java error handling

Learn how to error handle the Java ArrayIndexOutOfBoundsException

How to troubleshoot Java ArrayIndexOutOfBoundsException


The `NullPointerException` (NPE) is quite a common and dreaded exception that you'll often encounter in Java when you try to use an object whose reference is `null`. That is to say, the reference does not point to an actual object but points to nothing or `null`.

## Reproducing the error

Below is a program which will recreate a `NullPointerException`.

```java
import java.time.Year;

public class Program {
    public static class Company {
        public final String name;
        public final int yearFounded;

        public Company(String name, int year) {
            this.name = name;
            this.yearFounded = year;
        }

        public int yearsInBusiness() {
            return Year.now().getValue() - this.yearFounded;
        }
    }

    public static void main(String[] args) {
        Company c1 = new Company("Sourcegraph", 2013);
        Company c2 = null;
        Company companies[] = new Company[]{c1, c2};

        for (int i = 0; i < companies.length; i++) {
            System.out.println(
                companies[i].name + " has been in business for " + 
                companies[i].yearsInBusiness() + " years."
            );

        }
    }
}
```

When we execute the above program, we will encounter a `NullPointerException` in our `for` loop. We add two companies to an array and then we iterate over the companies in a loop. Once the loop tries to print how long the _second_ company (`c2`) has been in business, it fails and prints the exception below.

```
Sourcegraph has been in business for 8 years.
Exception in thread "main" java.lang.NullPointerException
	at Program.main(Program.java:26)
```

Our `companies[]` array is made up of two companies `c1` and `c2`. When the `for` loop starts, it prints out information about the first company and then proceeds to the next company, `c2`. Unfortunately, `c2` has a `null` value so when we try to access anything that we expect a company object to have — like a `name` — we'll encounter a `NullPointerException` since `c2` does not point to _anything_.

## `If`-`else` to the rescue

We can make our `for` loop a little bit more robust by informing the user that a company whose value is `null` is not valid, otherwise, we print our usual statement. 

We can do this through the use of flow control by adding an `if`-`else` statement to our `for` loop.

```java
import java.time.Year;

public class Program {
    public static class Company {
        public final String name;
        public final int yearFounded;

        public Company(String name, int year) {
            this.name = name;
            this.yearFounded = year;
        }

        public int yearsInBusiness() {
            return Year.now().getValue() - this.yearFounded;
        }
    }

    public static void main(String[] args) {
        Company c1 = new Company("Sourcegraph", 2013);
        Company c2 = null;
        Company companies[] = new Company[]{c1, c2};

        for (int i = 0; i < companies.length; i++) {
            if (companies[i] == null) {
                System.out.println(
                    "Company at index " + i + 
                    " is null. Cannot print any information on null company"
                );
            } else {
                System.out.println(
                    companies[i].name + " has been in business for " + 
                    companies[i].yearsInBusiness() + " years."
                );
            }
        }
    }
}
```

In the output we receive below when our program executes, a message is printed to the user when it reaches a company whose value is `null` instead of throwing a `NullPointerException`.

```
Sourcegraph has been in business for 8 years.
Company at index 1 is null. Cannot print any information on null company
```

Here, we have prevented the error from occurring by providing user feedback for when an object is referencing a `null` value.

## Initialize all the things

We can also avoid the `NullPointerException` by ensuring that all the values that we use in our program are initialized.

```java
import java.time.Year;

public class Program {
    public static class Company {
        public final String name;
        public final int yearFounded;

        public Company(String name, int year) {
            this.name = name;
            this.yearFounded = year;
        }

        public int yearsInBusiness() {
            return Year.now().getValue() - this.yearFounded;
        }
    }

    public static void main(String[] args) {
        Company c1 = new Company("Sourcegraph", 2013);
        Company c2 = new Company("Y2K!", 2000);
        Company companies[] = new Company[]{c1, c2};

        for (int i = 0; i < companies.length; i++) {
                System.out.println(
                    companies[i].name + " has been in business for " + 
                    companies[i].yearsInBusiness() + " years."
                );
        }
    }
}

```

In our earlier programs, our second company `c2` had a `null` value, but in our above program, we initialize `c2` to a proper company object. 

With all our values in our program initialized, we don't encounter the `NullPointerException` anymore as can be indicated in the output below.

```
Sourcegraph has been in business for 8 years.
Y2K! has been in business for 21 years.
```

If you will have a `companies[]` array with many different companies, you can initialize all of them with stand-in data that can be modified later by programmers or users. 

## Learn more

Search across open source Java repositories that have the `NullPointerException` to further understand the message, and contextualize how others are handling the error in open source repositories.

<SourcegraphSearch query="NullPointerException lang:java" patternType="literal"/>

Check out more Sourcegraph Learn tutorials on [Java](https://learn.sourcegraph.com/tags/java).



NullPointerException in Java error handling

Learn how to error handle the Java NullPointerException

How to troubleshoot Java NullPointerException


The `StackOverflowError` is one of the most common runtime errors one can encounter in Java. This error occurs when we haven’t provided the proper terminating condition to our recursive function that results in an infinite loop.

When we call a method, a new stack frame is created on the call stack. This stack frame holds parameters of the called method, mostly the local variables and the return address of the method. The creation of these stack frames is iterative. During this process, if the Java Virtual Machine (JVM) runs out of space for the new stack frames, it throws a `StackOverflowError`.

## Reproducing the error

In our example Java file, we’ll define a recursive method, called `recursion()` that prints an integer and then calls itself with the successive integer as its argument. 

``` java
public class Main {
     
    public static void recursion(int num) {
        System.out.println("Number: " + num);
         
        if(num == 0)
            return;
        else
            recursion(++num);
    }
     
    public static void main(String[] args) {
        Main.recursion(1);
    }
}
```

When we compile and run the program, it starts printing numbers starting from 1 on, and thus the recursion never terminates. Depending on the JVM, the results may differ, but eventually the `StackOverflowError` is thrown.

```
Number: 1
Number: 2
Number: 3
Number: 4
Number: 5
...
Number: 5152
Number: 5153
Exception in thread "main" java.lang.StackOverflowError
    at java.base/java.io.Writer.write(Writer.java:249)
    at java.base/java.io.PrintStream.write(PrintStream.java:604)
    at java.base/java.io.PrintStream.print(PrintStream.java:745)
    at java.base/java.io.PrintStream.println(PrintStream.java:882)
    at Main.recursion(Main.java:4)
    at Main.recursion(Main.java:9)
    ...
    at Main.recursion(Main.java:9)
```  

You may need to scroll through considerable output to find the error. 

A program that has cyclic relationships between classes is also another situation where the `StackOverflowError` commonly occurs. Here's an example:

```java
public class A {
	public B type2;
	public A()
	{
		type2 = new B();    // Constructor of B is called hence object of A is created
	}

	public static void main(String[] args)
	{
			A type1 = new A();    // Cycle is started by invoking constructor of class A
	}
}

class B {
	public A type1;
	public B()
	{
		type1 = new A();    // Constructor of A is called hence object of A is created
	}
}
```

Once we compile and run the above program, we'll receive output similar to the following. 

```
...
Exception in thread "main" java.lang.StackOverflowError
	at B.<init>(A.java:18)
	at A.<init>(A.java:5)
	at B.<init>(A.java:18)
...
```

Cyclic relationships between classes is the result of two different classes instantiating each other inside their constructors. In the example, classes A and B instantiate each other in their contructors repeatedly until we get a `StackOverflowError`. 

Now, let's review the solution to prevent this error. 

## Add a terminating condition 

We must carefully inspect the stack, trace and detect the repetitive calls and try to introduce a proper terminating condition to ensure that the recursion terminates. We can avoid the error in the first example by adding a terminating condition.

```java
public class Main {
     
    public static void recursion(int num) {
        System.out.println("Number: " + num);
         
        if(num == 0)
            return;
        if(num == 5)
            return;
        else
            recursion(++num);
    }
     
    public static void main(String[] args) {
        Main.recursion(1);
    }
}
```

This program will print the numbers from 1 to 5:

```
Number: 1
Number: 2
Number: 3
Number: 4
Number: 5
```

Your terminating condition should make sense for the program you are building. Thinking through what would stop a given loop will make your program more effective and help you avoid the `StackOverflowError`. 

## Avoid unnecessary constructor calls

In our second example of cyclic relationships, the error is mainly due to unecessary constructor calls, so work to avoid introducing them in your code.
Another way of resolving this is to specify one as the parent and the other as the dependent. We can construct class `A` as the parent class and make class B the child, as demonstrated in the rewrite of the program below.

```java
public class A {
	public B type2;
	public A()
	{
		this.type2 = new B(this);  
        }  
	public static void main(String[] args)
	{
		A type1 = new A();    
        }
}
class B {
	public A type1;
	public B(A parent)
	{
		this.type1 = parent;    
        }
}
```

This solution prevents the recursive constructor calls and avoids the error.

## Increasing the stack size

If we expect we will need a lot of compute power ro tun our program, and anticipate a high number of loops or other ongoing processes, we can increase the stack’s size in order to allow a larger number of invocations. The default thread stack size may vary depending on the JVM installed. We can increase this stack size by using the `-Xss` flag.

The format of the `-Xss` argument is as follows. 

```sh
-Xss<size>[g|G|m|M|k|K]
```

This introduces the flag, and expects the size of the stack to be in gigabytes, megabytes, or kilobytes. 

For example, the following command sets the default stack size to 10 megabytes. 

```sh
java -Xss:10m myJavaApp.java
```

This argument needs to be passed when you start the application and can be specified either via the project’s configuration, or the command line. 

It is worth noting that computer memory is finite and it is generally recommended to focus on optimizing your program over increasing stack size unless you have a specific use case. 

## Learn more

Search across open source Java repositories that have the `StackOverflowError` to understand the message more and review it in context. 

<SourcegraphSearch query="StackOverflowError lang:java" patternType="literal"/>

Check out more Sourcegraph Learn tutorials on [Java](https://learn.sourcegraph.com/tags/java).


StackOverflowError in Java error handling

Learn how to error handle the Java StackOverflowError

How to troubleshoot Java StackOverflowError


In Java, whenever you try to get a character from a string and you specify a character index that is not within the string, you will get the following exception.

```
Exception in thread "main" java.lang.StringIndexOutOfBoundsException: String index out of range:
```

A String in Java is an array of characters and each character can be accessed by an index using the `.charAt()` method. When we use the `.charAt()` method and specify an index that does not exist in the underlying array of characters, Java will raise the above exception.

## Reproducing the error
Let's write the following Java program `ShowChar.java`.

```java
import java.util.Scanner;

public class ShowChar {

    public static void main(String[] args) {
        String word = "sourcegraph";
        Scanner scanner = new Scanner(System.in);

        System.out.println("The word is: '" + word + "'");
        System.out.print("show character at index? ");

        int index = scanner.nextInt();

        System.out.println(word + " has '" + word.charAt(index) + "' at index " + index);
    }
}
```

The program displays the word `sourcegraph` and allows the user to call a character at a given index that they input. Once an index has been given, the character at that index is displayed.

If the user enters `5` as the index, they won't encounter the `StringIndexOutOfBoundsException` as per the following output.

```
The word is: 'sourcegraph'
show character at index? 5
sourcegraph has 'e' at index 5
```

The length of the word `sourcegraph` is 11, which means there are 11 characters in the string.

A string consists of an array of characters and at each index is a character. Arrays in Java are zero indexed, which means the first index and consequently the first character in a string is at index 0 and the last character is at index 10. So if a user were to enter an index value larger than 10 or less than 0, like 12, they would be able to repoduce the `StringIndexOutOfBboundsException`.

```
Exception in thread "main" java.lang.StringIndexOutOfBoundsException: String index out of range: 12
	at java.base/java.lang.StringLatin1.charAt(StringLatin1.java:47)
	at java.base/java.lang.String.charAt(String.java:693)
	at ShowChar.main(ShowChar.java:14)
```

Now that we've been able to reproduce the error, let's go over possible solutions.

## Provide the user with the expected minimum and maximum values of an index

By using flow control and `if`-`else` statements, we can check that the index lies within the string. If the index does not lie within the string we can tell the user the minimum and maximum values we're expecting.

```java
import java.util.Scanner;

public class ShowChar {

    public static void main(String[] args) {
        String word = "sourcegraph";
        Scanner scanner = new Scanner(System.in);

        System.out.println("The word is '" + word + "' and has " + word.length() + " characters");
        System.out.print("Show character at index? ");

        int index = scanner.nextInt();

        int min = 0;
        int max = word.length() - 1;
        if (index >= min && index <= max) {
            char wordChar = word.charAt(index);
            System.out.println(word + " has the character '" + wordChar + "' at index " + index);
        } else {
            System.out.println("The given index " + index + " is incorrect.");
            System.out.println("The index can have a minimum value of 0 and a maximum value of " + max);
        }

    }
}
```

In the above program, we get the index value from the user and then we check that the index is greater than or equal to our minimum (0) and less than or equal to our maximum (11). We subtract 1 from the word length since arrays are zero indexed, so the first position is at 0 and last index is at 10.

If the user gives us an index value that is not within our minimum and maximum range, we print a message informing them what the minimum and maximum values are as indicated in the output below.

```
The word is 'sourcegraph' and has 11 characters
Show character at position? -1
The given index -1 is incorrect.
The index can have a minimum value of 0 and a maximum value of 10

```

Here we have handled the exception through providing feedback to the user via flow control.

## Use the absolute value and mod operator

We can use the modulus operator `%` to ensure the given index is always within our minimum and maximum range.

If we mod the given index with the length of the word, we can ensure that a given index is within the word. For example, say the index is 12 and the length of the word is 11 ex. `12 mod 11 = 1` the index is 1.

We can also ensure that the given index is always positive by taking the absolute value of the index using `Math.abs`.

```java
import java.util.Scanner;

public class ShowChar {

    public static void main(String[] args) {
        String word = "sourcegraph";
        Scanner scanner = new Scanner(System.in);

        System.out.println("The word is '" + word + "' and has " + word.length() + " characters");
        System.out.print("Show character at index? ");

        int value = scanner.nextInt();
        int max = word.length();
        value = Math.abs(value);

        int index = value % max;
        char wordChar = word.charAt(index);
        System.out.println(word + " has the character '" + wordChar + "' at index " + index);

    }
}
```

The above program is able to handle positive and negative values for the given index. We ensure the given value is positive with `Math.abs`. The modulus operator is used to ensure that the value is less than our maximum. 

```
The word is 'sourcegraph' and has 11 characters
Show character at index? 12
sourcegraph has the character 'o' at index 1

The word is 'sourcegraph' and has 11 characters
Show character at index? -1
sourcegraph has the character 'o' at index 1
```

As per the output above, an index larger than our maximum is wrapped around, which happens because `12 % 11` is `1`.

## Learn more

Search across open source Java repositories that have the `StringIndexOutOfBoundsException` to understand the message more.

<SourcegraphSearch query="StringIndexOutOfBoundsException lang:java" patternType="literal"/>

Check out more Sourcegraph Learn tutorials on [Java](https://learn.sourcegraph.com/tags/java).


StringIndexOutOfBoundsException in Java error handling

Learn how to error handle the Java StringIndexOutOfBoundsException

How to troubleshoot Java StringIndexOutOfBoundsException


If you are working in JavaScript, and receive the following output, the JavaScript engine detects an excessive level of recursion in your code.

```javascript
InternalError: too much recursion
```

A recursive function is a function that calls itself repeatedly. When a condition is met, the function stops calling itself. This is called a base case. If somehow the condition does not meet that condition, then the function continues calling itself and the above error occurs.

In this tutorial, we'll reproduce the issue and then go over some solutions.

## Reproducing the error

Let's write the following program, `factorial.js`.

```javascript
function factorial(x) {
  return x * factorial(x - 1)
}
num = 5
console.log(factorial(num))
```

This small program calculates the factorial of number `num` which is initialized as `5` in this case. This recursive function is missing a base case. As there is no exit condition, the function will call itself infinitely.

```javascript
factorial.js:1
function factorial(x) {
                  ^
RangeError: Maximum call stack size exceeded
    at factorial (factorial.js:1:19)
    at factorial (/runtime/javascript/3xdbg257u/factorial.js:3:12)
    at factorial (/runtime/javascript/3xdbg257u/factorial.js:3:12)
    at factorial (/runtime/javascript/3xdbg257u/factorial.js:3:12)
    at factorial (/runtime/javascript/3xdbg257u/factorial.js:3:12)
    at factorial (/runtime/javascript/3xdbg257u/factorial.js:3:12)
    at factorial (/runtime/javascript/3xdbg257u/factorial.js:3:12)
    at factorial (/runtime/javascript/3xdbg257u/factorial.js:3:12)
    at factorial (/runtime/javascript/3xdbg257u/factorial.js:3:12)
    at factorial (/runtime/javascript/3xdbg257u/factorial.js:3:12)
...
```

Now that we have been able to reproduce the error, let's go over possible solutions.

## Specifying a base case condition

We know that in mathematics, a factorial of negative numbers is not defined, so we can use this as our base case condition.

```javascript
function factorial(x) {
  if (x === 0) {
    return 1
  }
  return x * factorial(x - 1)
}
num = 5
console.log(factorial(num))
```

In this example, `factorial(5)` asks for `factorial(4)`, `factorial(4)` asks for `factorial(3)` and so on. At some point we arrive at `factorial(0)` which returns `1`. The following is the output we receive.

```javascript
Output: 120
```

Hence, by explicitly providing the condition where the recursion will stop, we won't receive the `too much recursion` error.

## Using a `while` loop

We can also implement the following program using a `while` loop. In this example, we are calculating the factorial of number using while loop.

```javascript
num = 5
factorial = 1

while (num > 0) {
  factorial = factorial * num
  num--
}

console.log(factorial)
```

In each iteration we are multiplying the current value `num` with `factorial` and then decrementing `num` by 1.

```javascript
Output: 120
```

Since the base condition that will stop the recursion is also specified here (`num > 0`), we avoid the `too much recursion` error.

## Learn more

Search across open source JavaScript repositories that have the `InternalError` to further understand and explore the error message.

<SourcegraphSearch query="InternalError: too much recursion" patternType="literal"/>

Check out more Sourcegraph Learn tutorials on [JavaScript](https://learn.sourcegraph.com/tags/javascript).


InternalError, too much recursion in JavaScript error handling

Learn how to error handle JavaScript InternalError too much recursion

How to troubleshoot JavaScript InternalError too much recursion


If you are working in JavaScript, and receive one of the following outputs, your code is attempting to access properties of `null` and `undefined`.

```js
TypeError: null has no properties 
TypeError: undefined has no properties 
TypeError: Cannot read property {x} of null
TypeError: Cannot read property {x} of undefined
TypeError: Unable to get property {x} of undefined or null reference
```

In JavaScript, `null` and `undefined` have no properties. This is why this error is being raised.

Depending on the browser, the message of the error will vary between the outputs described before.

In this tutorial, we'll reproduce the issue and then go over some solutions.

## Reproducing the error

Let's execute the following in a JavaScript console. In this first example, we will use `null`.

```js
console.log(null.name);  // TypeError: Cannot read property 'name' of null
```

In this second example, we will use `undefined`.

```js
console.log(undefined.name);  // TypeError: Cannot read property 'name' of undefined
```

Now that we have been able to reproduce the error, let's go over possible solutions.

## Review your code

In the examples above, it is pretty clear that we are trying to access a property of `null` or `undefined`. But in other cases this will be less obvious. Let's consider another example.

```js
let person = null;

if (Date.now() < new Date(2022,11,01)) {
    person = {
        "name": "Michelle"
    }
}

console.log(person.name);
```

**What about this code?** If you run this program before November 1, 2022 it will work as expected. The output will be `Michelle`. 
But if you run this code after that date, the variable `person` won't be changed and it will have a property of `null`, so we are going to receive the `TypeError`.

So, we need to be careful about this kind of code that can have different values.

## Check before accessing

If we have a program like the one in the previous section, we can avoid this exception being raised by checking if the variable is what we are expecting, before using it.

```js
let person = null;

if (Date.now() < new Date(2021,11,01)) {
    person = {
        "name": "Michelle"
    }
}

if (person != null) {
    console.log(person.name);
} else {
    console.error("I don't know the person's name :( ")
}
```

*Note that when comparing this way: `!= null` the result will be `true` only if the variable is not null and not undefined. See more about this in the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null#difference_between_null_and_undefined).*

This way we can let the user know that something is missing but with a more human-readable message.

## Exception handling

A third approach is to handle the exception with a `try` / `catch` clause that catches the `TypeError` and shows a human-readable message for the user.

```js
let person = null;

if (Date.now() < new Date(2022,11,01)) {
    person = {
        "name": "Michelle"
    }
}

try {
    console.log(person.name);
} catch (error) {
    if (error instanceof TypeError) {
        console.error("I don't know the person's name :( ")
    }
}
```

Exception handling with `try` / `catch` can help the program continue to run when exceptions occur, and can help your user understand program output more clearly.

## Learn more

Search across open source JavaScript repositories that have the `TypeError` to understand the message more.

<SourcegraphSearch query="TypeError: null has no properties lang:js" patternType="literal"/>

Check out more Sourcegraph Learn tutorials on [JavaScript](https://learn.sourcegraph.com/tags/javascript).


TypeError null has no properties in JavaScript error handling

Learn how to error handle JavaScript TypeError null has no properties

How to troubleshoot JavaScript TypeError null has no properties


When you are working in JavaScript, you may come across an error similar to the following.

```js
Error: Permission denied to access property "x"
```

Or, you may receive the error in a slightly more verbose form, like the following.

```js
Uncaught DOMException: Permission denied to access property "document" on cross-origin object
```

This error usually occurs when you try to access an object for which you have no permission, the most common
case is when you try to access a property of an `<iframe>` loaded from another domain for which you violated
the [same origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy).

## Reproducing the error

An example which causes the above error is this example document:

```html
<!DOCTYPE html>
<html>
  <head>
    <title>Example code</title>
    <meta charset="utf-8" />
    <script>
      window.onload = function() {
        console.log(window.frames[0].document);
      }
    </script>
  </head>
  <body>
    <iframe src="http://sourcegraph.com"></iframe>
  </body>
</html>
```

Depending on the browser you are using, you may receive a warning or a blank box where the site would normally be loaded.

![Iframe output error rendered on Firefox](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/iframe-javascript-firefox-error.png)
![Iframe output error, blank iframe in browser](https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/iframe-javascript-browser-error.png)

Now that we have reproduced the error, let's discuss possible solutions. 

## Solution

The recommended way to solve this error is to access properties that you control via an iframe. This will ensure that your code obeys the same-origin policy.

If you want to communicate with the iframe, you can use `window.postMessage()` if the embedded website has an event listener to handle the `message` event. Additionally, that message must be written in a way to allow communication cross-origin. 

_Please be sure to review the terms of service of websites you intend to incorporate onto your own domains. This tutorial is for demonstration purposes only._

For example, you can use the following HTML if you would like your website, `https://www.my-sourcegraph-website.com/` to be able to embed an html page hosted online at `https://www.a-third-party-page.com/`, you could write the file below. 


```html
<!DOCTYPE html>
<html>
  <head>
    <title>A third party website</title>
    <meta charset="utf-8" />
    <script>
      window.addEventListener("message", (event) => {
          if (event.origin !== "https://www.my-sourcegraph-website.com/") {
            return;
          }

          event.source.postMessage("Hello, " + event.data, event.origin)
      }, false)
    </script>
  </head>
  <body>
    <p>Hello world</p>
  </body>
</html>
```

Your website hosted on `https://www.my-sourcegraph-website.com/` will have the soucecode below. 

```html
<!DOCTYPE html>
<html>
  <head>
    <title>My Sourcegraph website</title>
    <meta charset="utf-8" />
    <script>
      window.addEventListener("message", (event) => {
        if (event.origin !== "https://www.a-third-party-page.com/") {
          // we don't trust the sender of the message
          return
        }

        const replyText = document.createElement("p");
        const textContent = document.createTextNode(event.data);
        replyText.appendChild(textContent);

        document.body.appendChild(replyText);
      }, false)

      window.onload = () => {
        const iframe = window.frames[0];
        iframe.postMessage("world!", "https://www.a-third-party-page.com/");
      }
    </script>
  </head>
  <body>
    <iframe src="https://www.a-third-party-page.com/"></iframe>
    <p>My very cool website</p>
  </body>
</html>
```

Notice how there is specific code to check who the message sender is, this would require an agreement with the owner of `https://www.a-third-party-page.com/` to allow you to communicate in a secure way. 

## Learn more

Search across open source JavaScript repositories that have the `Permission denied to access property "x"` error to understand the message more.

<SourcegraphSearch query="Permission denied to access property x" patternType="literal"/>

Check out more Sourcegraph Learn tutorials on [JavaScript](https://learn.sourcegraph.com/tags/javascript).

Error Permission denied to access property "x" in JavaScript error handling

Learn how to handle the JavaScript Error, Permission denied to access property "x"

How to troubleshoot JavaScript Error Permission denied to access property "x"


If you are working on a Linux terminal and you receive the following output, you are probably trying to access a file from the wrong directory. 

```sh
No such file or directory
```

In this tutorial, we'll reproduce the issue and then go over some solutions. Before we get started, you should ensure that you have correct filename and that it is free from typos.

## Reproducing the error

Let's create a directory `foo` and a file `bar.txt` inside of the `foo` directory. We can add some text data to the file so that it is not empty. 

Open your terminal and execute the following commands.

Create directory `foo` with the `mkdir` command. The `mkdir` command stands for "make directory" and will create a new directory in the directory you are currently located within on the terminal. 

```sh
mkdir foo
```

Create file `bar.txt` inside the `foo` directory. We will use the [`touch` command](https://en.wikipedia.org/wiki/Touch_(command)) to create this file.

```sh
touch foo/bar.txt
```

Write some data to the file `bar.txt` with the `echo` command, which returns back what we request.

```sh
echo "Hello, World" > foo/bar.txt
```

The above command uses `echo`, then the text we would like to add to our file in quotes, then the redirection operator `>`, and finally the name of our newly created text file, `bar.txt`.

Let's try to access the data using the `cat` or con**cat**enate command that will read data from the file and give its content as output.

```sh
cat foo/bar.txt
```

In this case, our ouput will be the following.

```
Hello, World
```

Now, let's try to acess the file with an incorrect path.

```sh
cat bar.txt
```

Because we have not changed directories into the `foo` directory, we'll receive the following output.

```
cat: bar.txt: No such file or directory
```

Now that we have been able to reproduce the error, let's go over possible solutions.

## Check current working directory

You can use the `pwd` command to check your current working directory. The `pwd` command stands for **p**resent **w**orking **d**irectory. You can then use the `ls` command to **l**i**s**t all the files present in the present directory. With these commands, you will get a better idea as to whether you are trying to access a given file through the correct filepath or not.

```sh
pwd
```

This command will return your current working directory.

```
/home/your-username
```

Next, type `ls` to list the contents of the present working directory.

```sh
ls
```

This will return a list of all directories and files present in your current directory. You may find output similar to the following, but note that output will be dependent on your actual directory.

```
Desktop foo Music Public Videos Documents Pictures Downloads Templates
```

Through observating the output above, you will notice that the file `bar.txt` is not present in current directory. You will need to move inside of the `foo` directory to access that file, as this is where you created `bar.txt`.

Use the `cd` command, which stands for **c**hange **d**irectory, to move inside the `foo` directory.

```sh
cd foo
```

This will move you into the `foo` directory, and your command prompt will change. In our example case, where we are in the user directory, the prompt will now be `~/foo$`.


Now we can check for files present in the `foo` directory.

```sh
ls
```

In our example, we have only one file in this directory, so our output will return the one file we have initialized there. 

```
bar.txt
```

Now that you are in the correct directory, you can check the contents of the file with `cat`. 

```
cat bar.txt
```

Your output will now be what we had expected.

```
Hello, World
```

If you are still experiencing issues finding your file or directory, always check for typos in the file name. Also check the path for the file and your current working directory.

## Use `whereis` command

It's possible that the file you are trying to access is a binary executable file, in this case you can use the `whereis` command to locate the binary. Open your terminal and type the following command, with `filename` standing in for the file you are looking for.

```sh
whereis filename
```

For example, you can search for the location of `netstat`, which is a command-line utility that displays active TCP connections and more.

```sh
whereis netstat
```

When you run the above command, you'll get the path to the location of `netstat`, which may be similar to the following output.

```
/usr/sbin/netstat
```

The `whereis` command will return all relevant paths where the binary executable is stored. This way you can check whether a particular binary exists on your system or not, then use Linux navigation commands, like the ones we went through above, to reach the particular binary and execute it.

## Learn more

Search across open source repositories that have the `No such file or directory` to understand the message more.

<SourcegraphSearch query="No such file or directory" patternType="literal"/>

Check out more Sourcegraph Learn tutorials on [Linux](https://learn.sourcegraph.com/tags/linux).


No such file or directory in Linux error handling

Learn how to error handle No such file or directory in Linux

How to troubleshoot Linux error No such file or directory


The Linux commands `cd` or `rmdir` will return the error `Not a directory` if you run them referencing a file that is not a directory (or folder). This can include a text file or a binary.

## Reproducing the error

Lets create a text file.

```bash
echo "test" > test
```

Let's try to change directory to the text file named `test` with the **c**hange **d**irectory (`cd`) command.

```bash
cd test
```

We'll receive the following error message.

```
cd: not a directory: test
```

The `cd` command fails because you've tried to change directory but passed a text file as an argument instead of a directory.

Now that we've reproduced the error, let's go over some possible solutions.

## Move the text file into a directory

The most straightforward way of avoiding this error is by using `cd` only on known directories.

First, we create a directory.

```bash
mkdir mydir
```

Then we can move our text file, `test` into that directory.

```bash
mv test mydir/test
```

Finally we can now change directory into `mydir`.

```bash
cd mydir
```

You can ensure that the file is in `mydir` by running the `ls` — or _list_ — command.

## Use `ls` to check if the file is a directory first

You can use `ls` to list all files in a directory. We will append the flags `-lah`:

* `-l` — list files verbosely in long-form, showing more detail
* `-a` — list all files, not ignoring files that begin with `.`
* `-h` — list file sizes in a human-readable format, as in `5K`, `250M`, `96B`


```bash
ls -lah
```

Once you run the command, you should receive output similar to the following based on your own file structure. 

```
total 1848
-rw-r--r--    1 user  Users   156B 11 Oct 12:17 .babelrc
-rw-r--r--    1 user  Users    72B 11 Oct 12:24 .env
-rw-r--r--    1 user  Users   204B 11 Oct 20:12 .eslintrc.js
-rw-r--r--    1 user  Users   390B 11 Oct 12:17 .eslintrc.json
drwxr-xr-x   14 user  Users   448B 11 Oct 20:25 .git
drwxr-xr-x    3 user  Users    96B 11 Oct 12:17 .githooks
drwxr-xr-x    4 user  Users   128B 11 Oct 12:17 .github
...
```

The start of each output lets you know if it's a directory or not. `-` means it's a regular file (as in `-rw-r--r--`) and `d` means it is a directory (as in `drwxr-xr-x`). Be sure to use `cd` only on directories that are indicated as such. 

## Use `grep` to filter only directories

You can use the `grep` command to list only directories. This way if you use `cd` on any of those, it should succeed. `grep` is used to filter out all regular files so only directories remain in the list.

```bash
ls -lAh | grep "^d"
```

After running this comand, you'll only receive the output of directories in the example of the section above. 

```
drwxr-xr-x   14 user  Users   448B 11 Oct 20:25 .git
drwxr-xr-x    3 user  Users    96B 11 Oct 12:17 .githooks
drwxr-xr-x    4 user  Users   128B 11 Oct 12:17 .github
...
```

With `grep` you can filter out the files and directories you are looking for to ensure you are not using a command that will not run on a given type. 


## Learn more

Search across open source Linux repositories that have the `Not a directory` to understand the message more.

<SourcegraphSearch query="Not a directory" patternType="literal"/>

Check out more Sourcegraph Learn tutorials on [Linux](https://learn.sourcegraph.com/tags/linux).


Not a directory in Linux error handling

Learn how to error handle Not a directory in Linux

How to troubleshoot Linux error Not a directory


When you are working with PHP, you may receive this message:

```
unexpected end of file, expecting ';' or ','
```

This means that you haven't finished your command or haven't written it completely. Programming languages ​​like PHP use a specific character to define the end of a command (`;`), so they can understand what to run at what time. When you don't enter this character, the PHP interpreter thinks it's an unfinished command and throws an error.

## Reproducing the error

Let's consider this in practice. Assuming that you have PHP installed on your machine, write this little piece of code in a `hello.php` file:

```php
<?php

echo 'Hello World'

```
Now, you can run the file on terminal in the same path of the file. 

```sh
php hello.php
```

Then you'll receive the error on output:

```
Parse error:  syntax error, unexpected end of file, expecting "," or ";" in /path/to/hello.php on line 4
```

Now that we reproduced the error, let's find out how to fix it.

## Finish the command with `;`

As we saw before, the PHP programming language uses some characters to define the end of a command or a concatenation of commands. So, in our `hello.php` file, add `;` at the end of the `echo` command:

```php
<?php

echo 'Hello World';

```

If you run this file, the output of will now be `Hello World`. 

## When to use ","? 

You may have noticed that the error message suggests two characters that may have been missing in the code: `syntax error, unexpected end of file, expecting "," or ";"`. So, if we put a `;` at the end of the `echo` expression works, what happens when we put a `,`? Let's run this experiment by writing the program with a comma at the end of the expression.

```php
<?php

echo 'Hello World',

```

Run the command with `php`.

```shell
php hello.php
```

You'll now receive a new error message.

```
Parse error:  syntax error, unexpected end of file in /path/to/hello.php on line 4
```

This experiment didn't work at all, but why? 

Because in PHP, the `,` character is used to concatenate expressions in the `echo` command. That's why the first error suggests `;` or `,` — because the interpreter doesn't know if you intended to write that code or concatenate it with more expressions

So, let's review a program that uses both characters (`,` and `;`):

```php
<?php

$name = 'Sourcegraph';

echo 'Hello ', $name;

```

Run the program again.

```shell
php hello.php
```

The output of the file execution will be the following.

```
Hello Sourcegraph
```

You have now solved the error message and can be sure to end your expressions as needed. If you encounter this error again, check the end of your file. 

## Learn more

Search across open source PHP repositories that have this `SyntaxError` to understand the message more.

<SourcegraphSearch query="&quot;unexpected end of file, expecting ';' or ','&quot; lang:php" patternType="literal"/>

Check out more Sourcegraph Learn tutorials on [PHP](https://learn.sourcegraph.com/tags/php).

Syntax error, unexpected end of file, expecting ';' or ',' in PHP error handling

Learn how to error handle PHP syntax error, unexpected end of file, expecting ';' or ','

How to troubleshoot PHP syntax error unexpected end of file, expecting ';' or ','


If you are working in Python, and receive the following output, your code is attempting to access an identifier that is not defined. This could be in either the local or global scope of the program.

```python
NameError: name 'spam' is not defined
```

In this tutorial, we'll reproduce the issue and then go over some solutions.

## Reproducing the error

Let's write the following program, `name_error.py`. 

```python
def handler():
    spam = input("Enter a spam message: ")
    prnt(spam)

handler()
```

This small program creates a function that reads a spam message from the user and stores it into the `spam` variable and tries to print it. But, within this program, we have misspelled `print` as `prnt`.

If the program had `print` as it was meant to be, then the output is as indicated below.

```sh
Enter a spam message: It's a spam!!
It's a spam!!
```

With the misspelled function `prnt`, we are able to reproduce the `NameError`.

```sh
Enter a spam message: It's a spam!!
Traceback (most recent call last):
  File "name_error.py", line 5, in <module>
    handler()
  File "name_error.py", line 3, in handler
    prnt(spam)
NameError: name 'prnt' is not defined
```

There are several causes for the Python `NameError`, which we'll describe in more detail below.

## General causes for `NameError`

The example we used above was a misspelling of a built-in function that causes the `NameError`. Below are the general causes for this issue.

### Misspelling built-in functions

This is how we reproduced the `NameError` in the above section that included the misspelling of the built-in function `print()` as `prnt()`. 

In this instance, a recovery is possible through spell-checking your built-in functions. IDEs (code editors) often provide support for this through underlining code that may be incorrect (as in word processing programs), or offer [spelling](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) [extensions](https://marketplace.visualstudio.com/items?itemName=ban.spellright).

### Using undefined variables

If you attempt to call a variable before defining it, you will also receive a `NameError` error message. 

```python
a = 10
print(b)
```

In this case, you'll receive output similar to the following.

```sh
NameError: name 'b' is not defined
```

One way to recover from this error would be to ensure that you are only calling defined variables, or to define the missing variable after receiving the above error. 

### Using a variable prior to defining it

Similar to the example above, if you call a variable prior to defining it, you will also receive the `NameError` from the Python interpreter, as in this example that uses `a` in a function prior to its definition. 

```python
print(a)
a = 10
``` 

Here, you will receive the guidance that `a` is not defined. 


```sh
NameError: name 'a' is not defined
```

In these cases, you can be sure that you define variables prior to usage. You will often want to define all variables early on in the writing of your program.

### Incorrect usage of scope

When writing programs in Python, you should be aware of the scope of your variables. In the example below, `spam` is defined within the `handler()` function, and is therefore scoped locally to the function. However, we try to call the variable outside of the function context. 

```python
def handler():
    spam = input("Enter a spam message: ")
    print(spam)

handler()
print(spam) #using spam outside the handler function
```

Because we have attempted to use `spam` within a global context outside of the function it belongs to, we receive the following `NameError` message as output, which states that `spam` is not defined.

```sh
Traceback (most recent call last):
  File "name_error.py", line 6, in <module>
    print(spam)
NameError: name 'spam' is not defined
```

In this case, we coud rewrite the program to make `spam` a global variable, defining it outside of the context of the `handler()` function. This ensures that both the function and the rest of the program can access the `spam` variable.

```python
spam = input("Enter a spam message: ")

def handler():
    print(spam)

handler()
print(spam)
```

While this is creating redundant code that prints `spam` twice, we no longer receive an error message. In this case, it would be worthwhile to think through what you are attempting to do and to consider how to scope your variables prior to releasing your program. You can learn more about Python scope through [W3Schools](https://www.w3schools.com/python/python_scope.asp).

In the next section, we will walk you through a solution that is universal to all of the examples above. 

## Exception handling

The reccomended approach to preventing the `NameError` from stopping your program is to handle the exception with a `try` / `except` clause that calls the `NameError`.

```python
def handler():
    try:
        print(spam)
        spam = input("Enter a spam message: ")
    
    except NameError:
        print('You are attempting to access an identifier that is not defined in the local or global scope.')

handler()
```

Here, we first have the program attempt our original workflow, but use the `except` clause to handle the `NameError` that we have anticipated. 

```sh
You are attempting to access an identifier that is not defined in the local or global scope.
```

In this example, we have told the user that they cannot use an identifier that is not defined, because they are calling the `spam` variable prior to defining it.

## Learn more

Search across open source Python repositories that have the `NameError` to understand the message more.

<SourcegraphSearch query="NameError lang:python" patternType="literal"/>

Read the official Python docs on [Errors and Exceptions](https://docs.python.org/3/tutorial/errors.html).

Check out more Sourcegraph Learn tutorials on [Python](https://learn.sourcegraph.com/tags/python).

NameError in Python error handling

Learn how to error handle the Python NameError

How to troubleshoot Python NameError


If you are working in Python, and receive the following output, your code is attempting to make an OS operation that fails.

```python
OSError: [Errno X] description of the error
```

This error is raised by the [`os` module](https://docs.python.org/3/library/os.html) in Python when a system function 
returns a system-related error, including I/O (or input/output) failures.

It provides the numeric error code (`Errno`) and the corresponding error message as provided by the operating system.

In this tutorial, we'll reproduce the issue with one of the most common system functions — `open()` — and then go over some solutions.

*Keep in mind that there are other OS functions that raise `OSError`. You can review [Python os documentation](https://docs.python.org/3/library/os.html) for more information about the system functions that could raise this exception.*

## Reproducing the error

Let's write the following program: `open_file.py`. 

```python
import os


def open_file():
    os.open("ghost_file.txt", os.O_RDONLY)

open_file()

```

This small program tries to open the file `ghost_file.txt` in read-only mode but this file 
does not exist in our filesystem. So, the function `open()` throws the following exception:

```
OSError: [Errno 2] No such file or directory: 'ghost_file.txt'
```

Now that we have been able to reproduce the error, let's go over possible solutions.

## Catch the exception

You can use a `try` / `except` clause to catch this exception and show another message, log the result, or just ignore it. In our example, we'll print a message to the user so that they can recover from the error. 

```python
import os


def open_file():
    try:
        os.open("ghost_file.txt", os.O_RDONLY)
    except OSError as error:
        print(error)  # This will print the error message as we received before
        print(
            """
            Oops! The file you are looking for is not here.
            Maybe you need to create it first?
            """
            )

open_file()

```

Here, we first have the program attempt our original workflow, but use the `except` clause to handle the `OSError` that we have anticipated. 

```
[Errno 2] No such file or directory: 'ghost_file.txt'

            Oops! The file you are looking for is not here. 
            Maybe you need to create it first?
```

In this example, we have told the user that they cannot open the file if it does not exist and also printed the original error.

## Create the file if it does not exist

The `open` function has an option that indicates to Python to create the file if it does not exist. 
This will prevent the exception from being raised by creating a `ghost_file.txt` in your filesystem and opening it.

```python
import os


def open_file():
    os.open("ghost_file.txt", os.O_CREAT)

open_file()

```

At this point, if we run `ls` to list the contents of our working directory, we will discover that `ghost_file.txt` has been created and we will no longer experience this error. 

## Learn more

Search across open source Python repositories that have the `OSError` to better understand the message and how others are handling the error.

<SourcegraphSearch query="OSError lang:python" patternType="literal"/>

Read the official Python docs on [Errors and Exceptions](https://docs.python.org/3/tutorial/errors.html).

Check out more Sourcegraph Learn tutorials on [Python](https://learn.sourcegraph.com/tags/python).


OSError in Python error handling

Learn how to error handle the Python OSError

How to troubleshoot Python OSError


If you are working in Python, and receive the following output, your code is attempting to divide a given number by zero.

```python
ZeroDivisionError: division by zero
```

In mathematics, division by 0 is undefined. Because of this, Python will issue the above error when your code tries to accomplish this undefined expression. 

In this tutorial, we'll reproduce the issue and then go over some solutions.

## Reproducing the error

Let's write the following program, `divide.py`. 

```python
def divide_two_numbers():
    a = input("Enter an integer: ")
    b = input("Enter another integer: ")

    c = int(a)/int(b)
    print(c)

divide_two_numbers()
```

This small program creates a function that divides `a` by `b` to return `c`. The integers `a` and `b` are input by the user of the program, so a user can unknowingly enter `0` as the second integer.

If the user enters `9` and then `3`, there will be no errors returned, as indicated in the output below.

```python
Enter an integer: 9
Enter another integer: 3
3.0
```

If, however, the user enters `9` and then `0`, we will be able to reproduce the `ZeroDivisionError`.

```python
Traceback (most recent call last):
  File "divide.py", line 8, in <module>
    divide_two_numbers()
  File "divide.py", line 5, in divide_two_numbers
    c = int(a)/int(b)
ZeroDivisionError: division by zero
```

Now that we have been able to reproduce the error, let's go over possible solutions.

## Return 0

You can use flow control in the form of an `if` / `else` statement to reach an alternate outcome. 

```python
def divide_two_numbers():
    a = input("Enter an integer: ")
    b = input("Enter another integer: ")

    c = (int(a)/int(b)) if int(b) != 0 else 0
    print(c)

divide_two_numbers()
```

In this example, we have the program check to ensure that `b` is not equal to `0`, and if it is to instead print `0`. In this case, our output with a `0` denominator would be a `0`.

```python
Enter an integer: 9
Enter another integer: 0
0
```

While this solution prevents an error, it does not give the feedback that our expression is undefined, and may not be the best solution for you, depending on the requirements of your program.

## Return a string with guidance 

Flow control and an `if` / `else` statement can also be used to print output to give guidance, or give the user direction.

```python
def divide_two_numbers():
    a = input("Enter an integer: ")
    b = input("Enter another integer: ")

    if int(b) == 0:
        c = "This expression is undefined."

    else:
        c = int(a)/int(b)

    print(c)

divide_two_numbers()
```

Here, we first check whether `b` is equivalent to `0`, and if so, we initialize `c` as a string that states that `This expression is undefined.`

```python
Enter an integer: 9
Enter another integer: 0
This expression is undefined.
```

You may want to provide even more guidance to the user, to let them know that they can't divide by `0`, or to put this workflow in a loop so that the user can try again.

## Exception handling

A third approach is to handle the exception with a `try` / `except` clause that calls the `ZeroDivisionError`.

```python
def divide_two_numbers():

    try:
        a = input("Enter an integer: ")
        b = input("Enter another integer: ")

        c = int(a)/int(b)

    except ZeroDivisionError:
        c = "You cannot divide by 0."

    print(c)

divide_two_numbers()
```

Here, we first have the program attempt our original workflow, but use the `except` clause to handle the `ZeroDivisionError` that we have anticipated. 

```python
Enter an integer: 9
Enter another integer: 0
You cannot divide by 0.
```

In this example, we have told the user that they cannot divide by 0 if they attempt to do so.

## Learn more

Search across open source Python repositories that have the `ZeroDivisionError` to understand the message more.

<SourcegraphSearch query="ZeroDivisionError: division by zero lang:python" patternType="literal"/>

Read the official Python docs on [Errors and Exceptions](https://docs.python.org/3/tutorial/errors.html).

Check out more Sourcegraph Learn tutorials on [Python](https://learn.sourcegraph.com/tags/python).

ZeroDivisionError division by zero in Python error handling

Learn how to error handle the Python ZeroDivisionError, division by zero

How to troubleshoot Python ZeroDivisionError


There may be times when an exception is thrown in Python and you might want to wrap that exception in another one in order to provide more information. You can accomplish this while providing messages for both exceptions in a full traceback. 

Here, we will observe the difference between this type of chaining and cases where an exception is raised due to an error in handling another exception.

## An exception occurring during the handling of another exception

Consider the following exception for an index error:

```python
def example_mistake():
	try:
		[][1]
	except IndexError:
	    print('Indexing error', mistake)

example_mistake()
```

When we run this program, we'll call it `my_file.py`, we'll receive output similar to the following.

```
Traceback (most recent call last):
  File "my_file.py", line 3, in example_mistake
   [][1]
IndexError: list index out of range

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "my_file.py", line 7, in <module>
  File "my_file.py", line 5, in example_mistake
   print('Indexing error', mistake)
NameError: name 'mistake' is not defined

NameError: name 'mistake' is not defined
```

Notice the key phrase between the two tracebacks:

```
During handling of the above exception, another exception occurred:
``` 

Here, we observe the __context__ attribute of the exception object showing that another exception occurred within the handling of the original exception.

## Exception chaining

Now consider this next case where a developer can provide an improved error message. It is possible during the handling of one exception that another exception can occur. 

We know that when we are debugging it's useful to have information about all exceptions. The __cause__ attribute of the exception makes it possible to obtain the chaining by using the `raise ... from` statement in Python:

```python
def example_chaining():
	try:
		[][1]
	except IndexError as e:
		raise ValueError('Here is additional info: Invalid value') from e

example_chaining()
```

When you run this program, you'll receive output similar to the following. 

```
Traceback (most recent call last):
  File "my_file.py", line 3, in exampl_chaining
    [][1]
IndexError: list index out of range

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "my_file.py", line 7, in <module>
    example_chaining()
  File "my_file.py", line 5, in example_chaining
    raise ValueError('Here is additional info: Invalid value') from e
ValueError: Here is additional info: Invalid value
```

Again, notice the key phrase between the two tracebacks (`The above exception was the direct cause of the following exception:`). Here, that exception was wrapped with another one. Both exceptions are captured in the traceback.

## Disable chaining

Chaining can be disabled by using the `from None` motif within the `raise` clause. 

```python
def example_chaining_disabled():
	try:
		[][1]
	except IndexError:
		raise ValueError from None

example_chaining_disabled()
```

When you run this program, you will get output that is similar to what is below.

```
Traceback (most recent call last):
  File "my_file.py", line 7, in <module> example_chaining_disabled()
  File "my_file.py", line 5, in example_chaining_disabled
    raise ValueError from None
ValueError
```

Now you can differentiate the two types of chained exception tracebacks. 

## Learn more

Search across open source Python repositories that have the `raise ... from` motif to understand how developers are working with exceptions.

<SourcegraphSearch query="raise ... from lang:python" patternType="structural"/>

Read the official Python docs on [Exception Chaining](https://docs.python.org/3/tutorial/errors.html#exception-chaining).

Check out more Sourcegraph Learn tutorials on [Python](https://learn.sourcegraph.com/tags/python).

Exception Chaining in Python

Learn how to use Exception Chaining in Python

How to use Exception Chaining in Python


When working with a Git repository and performing actions like staging, unstaging, and committing, almost every command changes the state of your repository in some way.

The `git status` command provides a lot of information about the state of a Git repository at any given time. It lets you inspect changes in the staging area and working directory, which makes it particularly useful while staging and committing. The command’s output can help you better understand how a Git repository works and how different Git commands impact it.

In this guide, we’ll explore how to use `git status` and understand its output.

## Running the `git status` command

To get a summary of the status of the repository, run `git status` in your terminal in your repository directory. It doesn’t require any arguments.

```sh
git status
```

If you run the command on a freshly cloned repository, you will get the following output.

```
On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean
```

We can interpret the message as follows.

* `On branch main` — Our current branch
* `Your branch is up to date with 'origin/main'.` — Our local branch has the same commit history as the remote branch
* `nothing to commit` — There are no changes in the staging area
* `working tree clean` — There are no changes in the working directory, which means that the working directory is an exact copy of the latest commit

After running one command, we’ve learned about the current branch, its state relative to the remote branch, the state of the staging area, and the state of the working directory.

## Displaying changes in the working directory

When you’ve made some changes in the working directory, `git status` gives you information about which files have been modified, created, or deleted.

Suppose you run `git status` in a repository after making the following three changes in the working directory.

1. Modify a file named `index.html`
2. Create a new file named `style.css`
3. Delete a file named `script.js`

The following output demonstrates how `git status` represents these changes.

```
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add/rm <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   index.html
        deleted:    script.js

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        style.css

no changes added to commit (use "git add" and/or "git commit -a")
```

We can learn the following from the above output.

* `Changes not staged for commit` — Git is aware of the modified files listed in this section, but these modifications aren’t yet in the staging area (note that modified and deleted files are listed here, but not created files)
* `Untracked files` — This section lists new files that have been created but not yet added to the repository.
* `no changes added to commit` — No changes are staged to the staging area

When Git detects a new file in the working directory, it considers it “untracked.” Untracked files are newly created files that don’t exist in the repository’s current commit. They’re called “untracked” because Git hasn’t yet started tracking their changes.

## Understanding staged files

After you stage some changes, the output of `git status` will reflect this. Suppose we stage all of the above changes in the working directory by running `git add -A`, and then run `git status` again.

The output will now describe the contents of the staging area as follows.

```
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   index.html
        deleted:    script.js
        new file:   style.css
```

Note that a new section is now present, titled `Changes to be committed`. The sections that appeared previously, titled `Changes not staged for commit` and `Untracked files`, are no longer present. This reflects the fact that there are no unstaged changes remaining in the working directory. The file which was previously considered untracked is now in the staging area, so it’s labeled `new file` and is no longer untracked.

The changes listed in the `Changes to be committed` section will be included in the next commit when you run the `git commit` command. It’s often helpful to run `git status` to check your staged changes before committing and make sure you haven’t forgotten to stage any changes.

## Understanding renamed or moved files

After you move or rename files in the working directory, Git can’t initially determine that the files were moved or renamed. Instead, Git interprets the change as two separate changes: a deleted file and an untracked file.

Here’s the output from `git status` after renaming a file named `README.md` to `README2.md`:

```
Changes not staged for commit:
  (use "git add/rm <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        deleted:    README.md

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        README2.md
```

After you stage both of these changes, Git is able to determine that the contents of both files are identical. Based on this, Git will then list the change as a single entry  `Changes to be committed` section.

```
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        renamed:    README.md -> README2.md
```

The `renamed` label displays the file’s original name followed by its new name.

When moving files across directories, the change is displayed in a similar way. For example, if you move `README.md` to a new directory called `docs/pages`, the output will also list it as `renamed` and will display the file’s new location.

```
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        renamed:    README.md -> docs/pages/README.md
```

Git doesn’t differentiate between renaming and moving files. It represents both types of changes as “renamed” files.

## Understanding differences between local and remote branches

In addition to describing local changes, `git status` also reports the status of your current branch relative to its corresponding remote branch. To get an accurate result, the state of the remote branch must be fetched in Git. Run `git fetch` to ensure that your local repository is aware of the latest remote changes.

If your current branch is in an identical state to the remote branch, `git status` will state that the branch is up to date at the top of its output.

```
On branch main
Your branch is up to date with 'origin/main'.
```

In the above example, `origin/main` is the name of the remote branch. It’s prefixed with the name of the remote repository, which is `origin` by default.

If you’ve created some commits on your local branch and haven’t yet pushed them to the remote branch, `git status` will reflect this by indicating that your branch is ahead of the remote branch.

```
​​On branch main
Your branch is ahead of 'origin/main' by 2 commits.
  (use "git push" to publish your local commits)
```

On the other hand, if the remote branch contains commits that haven’t yet been pulled into your local branch, the output will indicate that your branch is behind the remote branch.

```
On branch main
Your branch is behind 'origin/main' by 3 commits, and can be fast-forwarded.
  (use "git pull" to update your local branch)
```

Both of the above situations are possible at the same time. You can have local commits that aren’t yet pushed while also having commits on the remote branch that you haven’t yet pulled. In this case, the output will describe the branches as having “diverged” and will display the number of commits on each.

```
On branch main
Your branch and 'origin/main' have diverged,
and have 2 and 3 different commits each, respectively.
  (use "git pull" to merge the remote branch into yours)
```

When collaborating with others or contributing to a remote repository, it’s useful to pay attention to the status of your local branch compared to the remote branch. This information lets you keep track of local commits that you can push and remote commits that need to be pulled.

## Using short output format

Once you’re used to reading the output of `git status`, you can use the short output option to get a more concise summary of the same information.

To run `git status` with the short output option, add the `-s` flag (which stands for “short”) to the command. 

```sh
git status -s
```

In a repository with a modified, deleted, and created file, the output will be similar to the following.

```
 M index.html
 D script.js
?? demo.js
```

The short output format provides the same list of files and their statuses as the default output format but in an abbreviated form. It displays a letter or symbol to indicate the state of each listed file, as described below.

* `M` — **m**odified
* `D` — **d**eleted
* `??` — untracked 

The short output format can be a convenient alternative to the default format. It’s particularly useful when you’re only interested in checking the status of changed files. If you want to know the current branch and its status relative to the remote branch, you still need to use the default longer format.

## Using verbose output format

The `git status` command also supports a verbose option that provides more details about staged changes.

To enable the verbose output option, run `git status` with the `-v` flag (short for “**v**erbose”).

```sh
git status -v
```

If you don’t have any staged changes, this will produce the same output as `git status` without the verbose option. However, if you do have staged changes, the command will describe every staged change by displaying the diff of the change.

```
On branch update-readme
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   index.html

diff --git a/index.html b/index.html
index a39afed..d8c7d8f 100644
--- a/index.html
+++ b/index.html
@@ -1,5 +1,5 @@
 <h1>JavaScrip Demo app</h1>
 
-<p>Please click the button below.</p>
+<p>Please click the button below to begin.</p>
 
 <button id="begin">Begin</button>
```

The above output indicates that the `index.html` file is staged and displays the details of the lines that were changed.

The verbose option is useful when you want to inspect the details of every staged change before committing. As an alternative, it’s also possible to use `git diff --staged` to display the details of every staged change as a diff. Read the [official documentation on the `git diff` command](https://git-scm.com/docs/git-diff) to learn more about displaying changes as diffs.

## Learn more

To learn about more ways you can inspect a Git repository’s state, check out the [`git log`](https://www.git-scm.com/docs/git-log) command, which lets you browse the commit history and learn about previously committed changes.

To display details about changes in the staging area, or about the changes made between commits, check out the [`git diff`](https://git-scm.com/docs/git-diff) command which lets you inspect changes line by line.

We also have several other tutorials and videos about Git that you can review:

* [How to stage and unstage files in Git](/how-to-stage-and-unstage-files-in-git)
* [How to commit code to a repository with the Git command-line interface](/how-to-commit-code-with-the-git-command-line-interface.md)
* [What are diffs in Git?](/what-are-diffs-in-git)
* [What are Git branches?](/what-are-git-branches)

Check out all of the available [Git tutorials on Sourcegraph Learn](/tags/git).


Learn how to use Git status to understand the state of a repository.

How to use the `git status` command to understand the state of a Git repository


Usability testing helps a team observe, understand, and draw insights from a user’s ability to complete a key set of tasks on their software product. It helps teams figure out if their target user can use their product, if users can navigate the key steps and processes involved, and if the user experience is accessible and seamless. Most importantly, through testing, developers and designers can identify usability issues and determine how to fix them. 

Usability testing is ideally conducted as part of the design phase while the prototype is still being tested and reiterated. This is a different process than User Acceptance Testing (UAT), which occurs near the end of development or shortly before deployment, and is a final check not often conducted on real users. 

This tutorial will focus on how to design and conduct an in-person usability test using a qualitative approach. This approach is relatively inexpensive and is more accessible for those who haven’t had training in formal scientific methods. In-person testing helps you find out whether the prototype works as intended, and it allows you to watch and talk to a user as they navigate the prototype. This method also provides considerable data to inform design and to translate these findings into improvements that address usability issues. 

## What you need

To begin the process, you’ll need the following:
* A prototype with a process that a user can test (this can be anything from a paper prototype to a full-fledged app)
* A target user group which we will describe in more detail below 
* A location to conduct usability testing 

In terms of materials, you should have the following:
* Recording equipment (either audio or video)
* Release forms
* Materials to take notes and synthesize results
* Compensation for participants

With these addressed, you are ready to continue.

## Step 1 — Identifying the project goals and users

First, you need to identify your goal by selecting a design or process that you want to test. 

For example, if you’re testing an image-sharing social media website that allows users to search, pin, and share content from other websites, a goal may be to identify whether users can easily navigate the homepage and search features. If you’re testing a mobile application like a rideshare app, your goal may be to find out whether users can successfully book a ride on an app. 

Next, you need to determine the target audience that your application serves and what problems it solves for them. For projects that may appeal to diverse audiences, focus on the type of person who may most benefit from your software. 

For instance, to test a rideshare app, you can try to find the type of user who fits a profile similar to the following:
* Does not own a car
* Lives in a city
* Tends to rely on public transportation often or daily

These users may have specific insights or problems you wouldn’t have known about had you only tested the general public without considering these parameters.

With our goals and users identified, we can continue to the planning stage.

## Step 2 — Planning the test

Now that you have narrowed down the scope of your test in terms of goals and users, you can move onto planning exactly what tasks you’ll ask the users to complete on your application design. The tasks should be relevant to a user’s needs and desires when using your app. 

If it’s a webapp, you can start by asking the testers to review the homepage and answer the following questions:
1. What are your thoughts?
1. What are you looking at?
1. What do you think you can do on this webapp?
1. What is the purpose of this webapp?

Next, you can ask the testers to walk through a task that best corresponds to your objective. Make sure you have planned for alternate paths and pages if a user goes in a different direction than intended. 

To return to the social media example: if you’re testing the search features, have participants search for content they’re interested in. If you’re interested in finding out if the content is easily shared, ask them to create, upload, and share a particular post or image. 

Consider coming up with a scenario or context to help guide the user if your website requires navigating complex information, such as a healthcare provider website or a process with many requirements: “You are a U.S. citizen looking for a marketplace health insurance plan, you’re single and live on your own, and you make $40,000 a year. Navigate this quiz to identify which plan best suits you.” Providing contextual information can help you standardize the results of the user test. 

To assess the success or failure of a task, decide on a number of tries or prompts before it’s marked as an issue. This will help you analyze the results later.

## Step 3 — Recruiting participants and setting up

Make a list of the characteristics of your target users for your usability test that you have identified in [Step 1](#step-1--identifying-the-project-goals-and-users). Then, translate these characteristics into specific, measurable criteria to use to identify those people. For example, if your aim is to test your design with “frequent social media users,” you may decide that this means they share content on a particular platform at least twice daily. 

Based on your target audience, create a screener questionnaire so that you can quickly figure out whether potential participants are a good fit for your test. Write questions that address each point in your criteria, without being overly specific. For example, a good question may be to ask about other social media platforms, such as “How often do you share content on TikTok or Instagram?” If there are any people who don’t fit your audience, identify their qualities (such as their age range, occupation, or if they don’t work in the discipline that the site is designed for) and write questions that help you filter out these individuals. 

Find at least five users (per test group, if you have more than one target user group). You can search for participants in industry-specific groups or online posting platforms like Craigslist or Facebook. Be clear and upfront about the time commitment. Consider testing with colleagues and friends first to see if there are any major issues before refining the test. Then, schedule testing sessions with all participants and collect their names, email addresses, and phone numbers. 

Choose a form of compensation or incentive for participants: for instance, you can offer payment or gift cards, a discounted rate for your product or service, or access to a premium service. 

Finally, decide on where to conduct the tests. You can do guerilla usability testing in high-traffic locations like shopping malls, or you can do more planned tests in a conference room or office, or another relaxed setting where you would naturally find users of your application. Make sure there are no distractions, and that you can sit with participants while they test out the prototype. To record the tests, make arrangements for any audio or video equipment needed. 

## Step 4 — Writing a discussion guide 

It’s important to write both an interview script for the test facilitator and a set of instructions for the participants so that everyone receives the same test. You will also need to write a consent form to record participants, which you should distribute before the test. 

The interview script starts with asking background questions, then walks the participant through the tasks, and ends the test with some wrap-up questions to understand the user’s overall experience of the task, their satisfaction level and sources of confusion or frustration. The instructions for the participants take the participants through the tasks step by step. Below is a template with some questions to ask for each part of the test session. 

---
**Introduction**
1. Introduce yourself. 
2. Ask basic questions and chat to get to know a participant. 
3. Assure the participant that this is just an informal feedback session, that there are no right answers, and that they can’t do anything wrong. 
4. “Are you familiar with [a relevant topic, project, or tool]?” 

**Introduce the prototype.**
1. Ask what they think this app is for, whether they have background knowledge on related topics. 
2. Optionally ask other more specific questions about apps they use, the value they find in those tools, or about any experiences they’ve had using similar tools.
3. “Do you have any questions before we begin?”

**Walk-through of the prototype**
1. “What do you think of the layout or design of this app or page?”
2. Encourage them to think out loud as they go through the test so that you can understand every step in their thought process. 
3. Ask them to consider the first task, “What would you click on first?”
4. If you notice any unexpected behavior, you can observe this out loud and say, “That’s interesting. Can you tell me why you clicked on X or chose Y?”
5. If they ask questions or seem unsure about a task, ask them to articulate why. “What do you think you would do if you were to use this app in real life?”
6. If there are multiple ways of completing the task, ask if they see any other ways of doing so.

**Wrap-up**
1. Tell the participant that they’ve finished the test, and thank them for their very helpful feedback. 
2. Ask about what they enjoyed or disliked about the design and overall prototype. Alternatively, you could offer a short survey asking them to rate their level of satisfaction and frustration with the prototype. You may ask participants to rate statements on a scale of 1-5; for example, “The task was easy to complete” or “The task was too complicated.”
3. Follow up with a thank you email and their compensation or gift. 
---

This script will allow you and any other testers to have a standardized approach, and for participants to have a standardized experience. 

When writing a script, following the following guidance can help it be effective:
- Be concise and specific. Don’t use extra wording, because it may make the process seem intimidating or off-putting to the participants. 
- Reassure participants that you are testing the product and not their skills or intelligence.
- Remain neutral and don’t try to direct them or offer hints. 

For an example of a discussion guide, review this [conversational script](https://audioweb.sitehost.iu.edu/T284/krug_questions.html) from Steve Krug.

## Step 5 — Facilitating the test

A facilitator of a usability test observes the participant for any insights while remaining as non-interfering as possible. During the test, remind participants to verbalize their thought process if they fall silent; tell them that it’s important to know their thoughts as they go through the tasks to understand their perspective. 

The key things to observe during the test are: 
- How successfully a user can complete a task
- How often participants ask questions or seem hesitant or confused
- How satisfied the user seems with the experience 

Begin recording the test before you start the introduction portion, and take notes on what users say during and at the end of the test. You may want to collect these statements if you need to create a report — these are like abbreviated case studies that help you justify a redesign, if one is needed. 

If your prototype breaks some conventions in its text or design elements (such as an unusual menu icon or a different phrase for the “About” page), notice if users find this confusing or unclear. 

## Step 6 — Analyzing the results

Once you have your data from the test in the form of notes and/or recordings, it’s time to synthesize your findings. 

Start by reviewing the recordings and notes: all the positive feedback and user frustrations, their questions and hesitations, suggestions or comments. What went as expected and what didn’t? Try not to be too attached to any ideas of how you think the prototype should work. 

Then, record how many of the 5 test participants understood the design, clicked on the appropriate things, and completed the entire process. Write each piece of feedback or specific error onto individual sticky notes. Also write down any issues that came up, the type of error it was, any workarounds, and whether the issue is a serious obstacle in user satisfaction. 

Next, sort the sticky notes into groups based on similarity or theme in order to create a visual organization of your results. If you’re presenting your findings, you can also write a summary of key points or organize this information into a chart, bar graph, or another medium so that you can identify relevant patterns. 

Finally, discuss the most important themes you observed with your team. Identify a few key things to change in your next iteration.  

---
**A note on prioritizing issues:**

Evaluating the errors and the feedback you get depends on the type of application and what a user’s priorities are while using it. If some features could have serious consequences (affecting sales of a product, or leading to specific health outcomes due to your project being a healthcare app), make sure to mark any user frustrations or confusion that arise while testing. 

---

To return to our earlier examples — if you’re testing a state healthcare website, the tasks that are confusing or difficult to complete could have serious consequences for people, so it’s best to focus on making the website as clear and simple to use as possible. But if you’re testing a social media platform, it may be easy for users to complete a task, but because it’s not the only platform available, the design elements and seamlessness of the experience are just as important to become more widely adopted. So in this case, it’s better to focus on what testers find appealing or unpleasant about the design rather than just functionality.

## Step 7 — Making recommendations and improvements

To brainstorm potential improvements to your prototype, start with reviewing your team’s list of things to address from the previous step. Write down all the ways you might change your design, and don’t censor your ideas: at this stage, the point is to generate as many options as possible. 

If you get stuck, search for inspiration for potential solutions by researching other successful applications; what are their user flows or functionality that’s relevant to your app, even if it’s for a totally different service or product. 

Then, outline or sketch out new user flows to help you visualize the changes. 

In our Pinterest example, one issue could be that the search function only allows users to find content that’s tagged with the exact same search term they used, and not also related search content that other users may search for. The user could find it difficult to search for and share content widely, because the search results could be too narrow or limited. As a result, you may consider creating a tagging function that would help you expand your search results. You could also take inspiration from websites that display related searches of other users.

Lastly, assess which solutions generated best fit your original objectives for the test. Keep in mind that good changes resolve multiple issues when possible, are actionable and easy to understand, and use clear and concise language. Try to ensure that all the people who could potentially use your software will be satisfied with the changes. 

After implementing your changes, conduct another round of research to figure out if other issues were hiding under old issues or new issues were created by the new design. You may need to do this process a few times before you’re happy with the changes. 

## Conclusion

This tutorial outlined the main steps for creating and implementing an in-person usability test, along with key criteria and points of consideration to help you generate a test that works for your unique product and your project objectives. While the tools and programs used by user experience designers may change, a usability test is a rewarding practice that ensures your application is made with your target user’s needs in mind.



UX research for developers

User research and usability testing are important aspects of the software development process, this tutorial will guide you through the steps you need to take for a usability test on your software