dev install Git commands

docs/dev-guide/install.md

@@ -2,6 +2,8 @@
 # Developer Installation
 
 Installing ActivitySim as a developer is as easy as just using it with *uv*.
+The easiest wat to make sure you are up-to-date is to run `uv sync --locked`, 
+which will make sure that all the dependencies are loaded correctly.
 
 Depending on what you are working on, you may want to check out a branch
 other than the default `main`. To do so, you can use a `git switch` command
@@ -18,3 +20,68 @@ sure to use the `uv add` and `uv remove` commands so that the `pyproject.toml`
 and `uv.lock` files are updated correctly and your virtual environment is 
 updated.
 ```
+
+## Cloning from GitHub
+
+Developers who want to work on ActivitySim should clone the repository from GitHub.
+If you have the [GitHub command line tool](https://cli.github.com) installed, you 
+*could* run this command to clone the consortium's repository:
+
+```{sh}
+gh repo clone ActivitySim/activitysim
+```
+
+Usually, you'll actually not want to do this. Instead, **you should work on your
+own fork of the repository.** You can create a fork on GitHub using the web interface
+or the command line tool's [fork](https://cli.github.com/manual/gh_repo_fork) command.
+Then you would clone the repository by referencing your fork:
+
+```{sh}
+gh repo clone MyUsernameOrOrganization/activitysim
+```
+
+This way, you can make whatever changes you want in your fork and store them locally
+on your computer or push them to GitHub, and they definitely won't step on anyone
+else's work. When you're ready to share your awesome new features, you can open a
+pull request to do so.
+
+Also, you may notice that the consortium repository has a huge history and includes
+a lot of older data files that you probably don't need. To reduce your download time
+and disk space usage, you can tell Git that you don't want that whole history. If you
+just want to have access to the current code and a couple of years history, you can 
+cut off the older history using the `shallow-since` option:
+
+```{sh}
+gh repo clone MyUsernameOrOrganization/activitysim -- --shallow-since="2025-01-01"
+```
+
+This can reduce the cloning download and disk usage by several gigabytes! By default
+you won't see all your branches appear in this more limited clone, just the `main` 
+branch. 
+
+### Fetching a Specific Branch
+
+This is easily solved by downloading individual branches specifically by
+name. 
+
+```{sh}
+# change into the git repo's directory if not already there
+cd activitysim
+
+# Fetch the specific branch named "patch-67"
+git fetch origin refs/heads/patch-67:refs/remotes/origin/patch-67
+
+# Check out the branch as a local branch to work on
+git checkout -b patch-67 origin/patch-67
+```
+
+### Fetching All Branches in a Fork
+
+If you want to work more expansively, you may want to fetch all the branches in
+your fork, rather than getting specific branches one at a time. You can change the
+repo settings to do so by adding to the Git config file:
+
+```{sh}
+git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
+git fetch --shallow-since="2025-01-01" origin
+```

docs/dev-guide/install.md

@@ -2,6 +2,8 @@
 # Developer Installation
 
 Installing ActivitySim as a developer is as easy as just using it with *uv*.
+The easiest wat to make sure you are up-to-date is to run `uv sync --locked`, 
+which will make sure that all the dependencies are loaded correctly.
 
 Depending on what you are working on, you may want to check out a branch
 other than the default `main`. To do so, you can use a `git switch` command
@@ -18,3 +20,68 @@ sure to use the `uv add` and `uv remove` commands so that the `pyproject.toml`
 and `uv.lock` files are updated correctly and your virtual environment is 
 updated.
 ```
+
+## Cloning from GitHub
+
+Developers who want to work on ActivitySim should clone the repository from GitHub.
+If you have the [GitHub command line tool](https://cli.github.com) installed, you 
+*could* run this command to clone the consortium's repository:
+
+```{sh}
+gh repo clone ActivitySim/activitysim
+```
+
+Usually, you'll actually not want to do this. Instead, **you should work on your
+own fork of the repository.** You can create a fork on GitHub using the web interface
+or the command line tool's [fork](https://cli.github.com/manual/gh_repo_fork) command.
+Then you would clone the repository by referencing your fork:
+
+```{sh}
+gh repo clone MyUsernameOrOrganization/activitysim
+```
+
+This way, you can make whatever changes you want in your fork and store them locally
+on your computer or push them to GitHub, and they definitely won't step on anyone
+else's work. When you're ready to share your awesome new features, you can open a
+pull request to do so.
+
+Also, you may notice that the consortium repository has a huge history and includes
+a lot of older data files that you probably don't need. To reduce your download time
+and disk space usage, you can tell Git that you don't want that whole history. If you
+just want to have access to the current code and a couple of years history, you can 
+cut off the older history using the `shallow-since` option:
+
+```{sh}
+gh repo clone MyUsernameOrOrganization/activitysim -- --shallow-since="2025-01-01"
+```
+
+This can reduce the cloning download and disk usage by several gigabytes! By default
+you won't see all your branches appear in this more limited clone, just the `main` 
+branch. 
+
+### Fetching a Specific Branch
+
+This is easily solved by downloading individual branches specifically by
+name. 
+
+```{sh}
+# change into the git repo's directory if not already there
+cd activitysim
+
+# Fetch the specific branch named "patch-67"
+git fetch origin refs/heads/patch-67:refs/remotes/origin/patch-67
+
+# Check out the branch as a local branch to work on
+git checkout -b patch-67 origin/patch-67
+```
+
+### Fetching All Branches in a Fork
+
+If you want to work more expansively, you may want to fetch all the branches in
+your fork, rather than getting specific branches one at a time. You can change the
+repo settings to do so by adding to the Git config file:
+
+```{sh}
+git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
+git fetch --shallow-since="2025-01-01" origin
+```

docs/dev-guide/install.md

@@ -2,6 +2,8 @@
 # Developer Installation
 
 Installing ActivitySim as a developer is as easy as just using it with *uv*.
+The easiest wat to make sure you are up-to-date is to run `uv sync --locked`, 
+which will make sure that all the dependencies are loaded correctly.
 
 Depending on what you are working on, you may want to check out a branch
 other than the default `main`. To do so, you can use a `git switch` command
@@ -18,3 +20,68 @@ sure to use the `uv add` and `uv remove` commands so that the `pyproject.toml`
 and `uv.lock` files are updated correctly and your virtual environment is 
 updated.
 ```
+
+## Cloning from GitHub
+
+Developers who want to work on ActivitySim should clone the repository from GitHub.
+If you have the [GitHub command line tool](https://cli.github.com) installed, you 
+*could* run this command to clone the consortium's repository:
+
+```{sh}
+gh repo clone ActivitySim/activitysim
+```
+
+Usually, you'll actually not want to do this. Instead, **you should work on your
+own fork of the repository.** You can create a fork on GitHub using the web interface
+or the command line tool's [fork](https://cli.github.com/manual/gh_repo_fork) command.
+Then you would clone the repository by referencing your fork:
+
+```{sh}
+gh repo clone MyUsernameOrOrganization/activitysim
+```
+
+This way, you can make whatever changes you want in your fork and store them locally
+on your computer or push them to GitHub, and they definitely won't step on anyone
+else's work. When you're ready to share your awesome new features, you can open a
+pull request to do so.
+
+Also, you may notice that the consortium repository has a huge history and includes
+a lot of older data files that you probably don't need. To reduce your download time
+and disk space usage, you can tell Git that you don't want that whole history. If you
+just want to have access to the current code and a couple of years history, you can 
+cut off the older history using the `shallow-since` option:
+
+```{sh}
+gh repo clone MyUsernameOrOrganization/activitysim -- --shallow-since="2025-01-01"
+```
+
+This can reduce the cloning download and disk usage by several gigabytes! By default
+you won't see all your branches appear in this more limited clone, just the `main` 
+branch. 
+
+### Fetching a Specific Branch
+
+This is easily solved by downloading individual branches specifically by
+name. 
+
+```{sh}
+# change into the git repo's directory if not already there
+cd activitysim
+
+# Fetch the specific branch named "patch-67"
+git fetch origin refs/heads/patch-67:refs/remotes/origin/patch-67
+
+# Check out the branch as a local branch to work on
+git checkout -b patch-67 origin/patch-67
+```
+
+### Fetching All Branches in a Fork
+
+If you want to work more expansively, you may want to fetch all the branches in
+your fork, rather than getting specific branches one at a time. You can change the
+repo settings to do so by adding to the Git config file:
+
+```{sh}
+git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
+git fetch --shallow-since="2025-01-01" origin
+```

docs/dev-guide/install.md

@@ -2,6 +2,8 @@
 # Developer Installation
 
 Installing ActivitySim as a developer is as easy as just using it with *uv*.
+The easiest wat to make sure you are up-to-date is to run `uv sync --locked`, 
+which will make sure that all the dependencies are loaded correctly.
 
 Depending on what you are working on, you may want to check out a branch
 other than the default `main`. To do so, you can use a `git switch` command
@@ -18,3 +20,68 @@ sure to use the `uv add` and `uv remove` commands so that the `pyproject.toml`
 and `uv.lock` files are updated correctly and your virtual environment is 
 updated.
 ```
+
+## Cloning from GitHub
+
+Developers who want to work on ActivitySim should clone the repository from GitHub.
+If you have the [GitHub command line tool](https://cli.github.com) installed, you 
+*could* run this command to clone the consortium's repository:
+
+```{sh}
+gh repo clone ActivitySim/activitysim
+```
+
+Usually, you'll actually not want to do this. Instead, **you should work on your
+own fork of the repository.** You can create a fork on GitHub using the web interface
+or the command line tool's [fork](https://cli.github.com/manual/gh_repo_fork) command.
+Then you would clone the repository by referencing your fork:
+
+```{sh}
+gh repo clone MyUsernameOrOrganization/activitysim
+```
+
+This way, you can make whatever changes you want in your fork and store them locally
+on your computer or push them to GitHub, and they definitely won't step on anyone
+else's work. When you're ready to share your awesome new features, you can open a
+pull request to do so.
+
+Also, you may notice that the consortium repository has a huge history and includes
+a lot of older data files that you probably don't need. To reduce your download time
+and disk space usage, you can tell Git that you don't want that whole history. If you
+just want to have access to the current code and a couple of years history, you can 
+cut off the older history using the `shallow-since` option:
+
+```{sh}
+gh repo clone MyUsernameOrOrganization/activitysim -- --shallow-since="2025-01-01"
+```
+
+This can reduce the cloning download and disk usage by several gigabytes! By default
+you won't see all your branches appear in this more limited clone, just the `main` 
+branch. 
+
+### Fetching a Specific Branch
+
+This is easily solved by downloading individual branches specifically by
+name. 
+
+```{sh}
+# change into the git repo's directory if not already there
+cd activitysim
+
+# Fetch the specific branch named "patch-67"
+git fetch origin refs/heads/patch-67:refs/remotes/origin/patch-67
+
+# Check out the branch as a local branch to work on
+git checkout -b patch-67 origin/patch-67
+```
+
+### Fetching All Branches in a Fork
+
+If you want to work more expansively, you may want to fetch all the branches in
+your fork, rather than getting specific branches one at a time. You can change the
+repo settings to do so by adding to the Git config file:
+
+```{sh}
+git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
+git fetch --shallow-since="2025-01-01" origin
+```

docs/dev-guide/install.md

@@ -2,6 +2,8 @@
 # Developer Installation
 
 Installing ActivitySim as a developer is as easy as just using it with *uv*.
+The easiest wat to make sure you are up-to-date is to run `uv sync --locked`, 
+which will make sure that all the dependencies are loaded correctly.
 
 Depending on what you are working on, you may want to check out a branch
 other than the default `main`. To do so, you can use a `git switch` command
@@ -18,3 +20,68 @@ sure to use the `uv add` and `uv remove` commands so that the `pyproject.toml`
 and `uv.lock` files are updated correctly and your virtual environment is 
 updated.
 ```
+
+## Cloning from GitHub
+
+Developers who want to work on ActivitySim should clone the repository from GitHub.
+If you have the [GitHub command line tool](https://cli.github.com) installed, you 
+*could* run this command to clone the consortium's repository:
+
+```{sh}
+gh repo clone ActivitySim/activitysim
+```
+
+Usually, you'll actually not want to do this. Instead, **you should work on your
+own fork of the repository.** You can create a fork on GitHub using the web interface
+or the command line tool's [fork](https://cli.github.com/manual/gh_repo_fork) command.
+Then you would clone the repository by referencing your fork:
+
+```{sh}
+gh repo clone MyUsernameOrOrganization/activitysim
+```
+
+This way, you can make whatever changes you want in your fork and store them locally
+on your computer or push them to GitHub, and they definitely won't step on anyone
+else's work. When you're ready to share your awesome new features, you can open a
+pull request to do so.
+
+Also, you may notice that the consortium repository has a huge history and includes
+a lot of older data files that you probably don't need. To reduce your download time
+and disk space usage, you can tell Git that you don't want that whole history. If you
+just want to have access to the current code and a couple of years history, you can 
+cut off the older history using the `shallow-since` option:
+
+```{sh}
+gh repo clone MyUsernameOrOrganization/activitysim -- --shallow-since="2025-01-01"
+```
+
+This can reduce the cloning download and disk usage by several gigabytes! By default
+you won't see all your branches appear in this more limited clone, just the `main` 
+branch. 
+
+### Fetching a Specific Branch
+
+This is easily solved by downloading individual branches specifically by
+name. 
+
+```{sh}
+# change into the git repo's directory if not already there
+cd activitysim
+
+# Fetch the specific branch named "patch-67"
+git fetch origin refs/heads/patch-67:refs/remotes/origin/patch-67
+
+# Check out the branch as a local branch to work on
+git checkout -b patch-67 origin/patch-67
+```
+
+### Fetching All Branches in a Fork
+
+If you want to work more expansively, you may want to fetch all the branches in
+your fork, rather than getting specific branches one at a time. You can change the
+repo settings to do so by adding to the Git config file:
+
+```{sh}
+git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
+git fetch --shallow-since="2025-01-01" origin
+```

docs/dev-guide/install.md

@@ -2,6 +2,8 @@
 # Developer Installation
 
 Installing ActivitySim as a developer is as easy as just using it with *uv*.
+The easiest wat to make sure you are up-to-date is to run `uv sync --locked`, 
+which will make sure that all the dependencies are loaded correctly.
 
 Depending on what you are working on, you may want to check out a branch
 other than the default `main`. To do so, you can use a `git switch` command
@@ -18,3 +20,68 @@ sure to use the `uv add` and `uv remove` commands so that the `pyproject.toml`
 and `uv.lock` files are updated correctly and your virtual environment is 
 updated.
 ```
+
+## Cloning from GitHub
+
+Developers who want to work on ActivitySim should clone the repository from GitHub.
+If you have the [GitHub command line tool](https://cli.github.com) installed, you 
+*could* run this command to clone the consortium's repository:
+
+```{sh}
+gh repo clone ActivitySim/activitysim
+```
+
+Usually, you'll actually not want to do this. Instead, **you should work on your
+own fork of the repository.** You can create a fork on GitHub using the web interface
+or the command line tool's [fork](https://cli.github.com/manual/gh_repo_fork) command.
+Then you would clone the repository by referencing your fork:
+
+```{sh}
+gh repo clone MyUsernameOrOrganization/activitysim
+```
+
+This way, you can make whatever changes you want in your fork and store them locally
+on your computer or push them to GitHub, and they definitely won't step on anyone
+else's work. When you're ready to share your awesome new features, you can open a
+pull request to do so.
+
+Also, you may notice that the consortium repository has a huge history and includes
+a lot of older data files that you probably don't need. To reduce your download time
+and disk space usage, you can tell Git that you don't want that whole history. If you
+just want to have access to the current code and a couple of years history, you can 
+cut off the older history using the `shallow-since` option:
+
+```{sh}
+gh repo clone MyUsernameOrOrganization/activitysim -- --shallow-since="2025-01-01"
+```
+
+This can reduce the cloning download and disk usage by several gigabytes! By default
+you won't see all your branches appear in this more limited clone, just the `main` 
+branch. 
+
+### Fetching a Specific Branch
+
+This is easily solved by downloading individual branches specifically by
+name. 
+
+```{sh}
+# change into the git repo's directory if not already there
+cd activitysim
+
+# Fetch the specific branch named "patch-67"
+git fetch origin refs/heads/patch-67:refs/remotes/origin/patch-67
+
+# Check out the branch as a local branch to work on
+git checkout -b patch-67 origin/patch-67
+```
+
+### Fetching All Branches in a Fork
+
+If you want to work more expansively, you may want to fetch all the branches in
+your fork, rather than getting specific branches one at a time. You can change the
+repo settings to do so by adding to the Git config file:
+
+```{sh}
+git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
+git fetch --shallow-since="2025-01-01" origin
+```

docs/dev-guide/install.md

@@ -2,6 +2,8 @@
 # Developer Installation
 
 Installing ActivitySim as a developer is as easy as just using it with *uv*.
+The easiest wat to make sure you are up-to-date is to run `uv sync --locked`, 
+which will make sure that all the dependencies are loaded correctly.
 
 Depending on what you are working on, you may want to check out a branch
 other than the default `main`. To do so, you can use a `git switch` command
@@ -18,3 +20,68 @@ sure to use the `uv add` and `uv remove` commands so that the `pyproject.toml`
 and `uv.lock` files are updated correctly and your virtual environment is 
 updated.
 ```
+
+## Cloning from GitHub
+
+Developers who want to work on ActivitySim should clone the repository from GitHub.
+If you have the [GitHub command line tool](https://cli.github.com) installed, you 
+*could* run this command to clone the consortium's repository:
+
+```{sh}
+gh repo clone ActivitySim/activitysim
+```
+
+Usually, you'll actually not want to do this. Instead, **you should work on your
+own fork of the repository.** You can create a fork on GitHub using the web interface
+or the command line tool's [fork](https://cli.github.com/manual/gh_repo_fork) command.
+Then you would clone the repository by referencing your fork:
+
+```{sh}
+gh repo clone MyUsernameOrOrganization/activitysim
+```
+
+This way, you can make whatever changes you want in your fork and store them locally
+on your computer or push them to GitHub, and they definitely won't step on anyone
+else's work. When you're ready to share your awesome new features, you can open a
+pull request to do so.
+
+Also, you may notice that the consortium repository has a huge history and includes
+a lot of older data files that you probably don't need. To reduce your download time
+and disk space usage, you can tell Git that you don't want that whole history. If you
+just want to have access to the current code and a couple of years history, you can 
+cut off the older history using the `shallow-since` option:
+
+```{sh}
+gh repo clone MyUsernameOrOrganization/activitysim -- --shallow-since="2025-01-01"
+```
+
+This can reduce the cloning download and disk usage by several gigabytes! By default
+you won't see all your branches appear in this more limited clone, just the `main` 
+branch. 
+
+### Fetching a Specific Branch
+
+This is easily solved by downloading individual branches specifically by
+name. 
+
+```{sh}
+# change into the git repo's directory if not already there
+cd activitysim
+
+# Fetch the specific branch named "patch-67"
+git fetch origin refs/heads/patch-67:refs/remotes/origin/patch-67
+
+# Check out the branch as a local branch to work on
+git checkout -b patch-67 origin/patch-67
+```
+
+### Fetching All Branches in a Fork
+
+If you want to work more expansively, you may want to fetch all the branches in
+your fork, rather than getting specific branches one at a time. You can change the
+repo settings to do so by adding to the Git config file:
+
+```{sh}
+git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
+git fetch --shallow-since="2025-01-01" origin
+```

docs/dev-guide/install.md

@@ -2,6 +2,8 @@
 # Developer Installation
 
 Installing ActivitySim as a developer is as easy as just using it with *uv*.
+The easiest wat to make sure you are up-to-date is to run `uv sync --locked`, 
+which will make sure that all the dependencies are loaded correctly.
 
 Depending on what you are working on, you may want to check out a branch
 other than the default `main`. To do so, you can use a `git switch` command
@@ -18,3 +20,68 @@ sure to use the `uv add` and `uv remove` commands so that the `pyproject.toml`
 and `uv.lock` files are updated correctly and your virtual environment is 
 updated.
 ```
+
+## Cloning from GitHub
+
+Developers who want to work on ActivitySim should clone the repository from GitHub.
+If you have the [GitHub command line tool](https://cli.github.com) installed, you 
+*could* run this command to clone the consortium's repository:
+
+```{sh}
+gh repo clone ActivitySim/activitysim
+```
+
+Usually, you'll actually not want to do this. Instead, **you should work on your
+own fork of the repository.** You can create a fork on GitHub using the web interface
+or the command line tool's [fork](https://cli.github.com/manual/gh_repo_fork) command.
+Then you would clone the repository by referencing your fork:
+
+```{sh}
+gh repo clone MyUsernameOrOrganization/activitysim
+```
+
+This way, you can make whatever changes you want in your fork and store them locally
+on your computer or push them to GitHub, and they definitely won't step on anyone
+else's work. When you're ready to share your awesome new features, you can open a
+pull request to do so.
+
+Also, you may notice that the consortium repository has a huge history and includes
+a lot of older data files that you probably don't need. To reduce your download time
+and disk space usage, you can tell Git that you don't want that whole history. If you
+just want to have access to the current code and a couple of years history, you can 
+cut off the older history using the `shallow-since` option:
+
+```{sh}
+gh repo clone MyUsernameOrOrganization/activitysim -- --shallow-since="2025-01-01"
+```
+
+This can reduce the cloning download and disk usage by several gigabytes! By default
+you won't see all your branches appear in this more limited clone, just the `main` 
+branch. 
+
+### Fetching a Specific Branch
+
+This is easily solved by downloading individual branches specifically by
+name. 
+
+```{sh}
+# change into the git repo's directory if not already there
+cd activitysim
+
+# Fetch the specific branch named "patch-67"
+git fetch origin refs/heads/patch-67:refs/remotes/origin/patch-67
+
+# Check out the branch as a local branch to work on
+git checkout -b patch-67 origin/patch-67
+```
+
+### Fetching All Branches in a Fork
+
+If you want to work more expansively, you may want to fetch all the branches in
+your fork, rather than getting specific branches one at a time. You can change the
+repo settings to do so by adding to the Git config file:
+
+```{sh}
+git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
+git fetch --shallow-since="2025-01-01" origin
+```