docs: Add version control and .gitignore best practices guide

[vincent067]

📝 Summary

This PR adds documentation on best practices for using .gitignore with Marimo, addressing the questions raised in #7708.

🔍 Changes

• Documents the recommended pattern to ignore __marimo__/ directories
• Explains what subdirectories are covered (cache/, session/, assets/)
• Provides guidance on when to commit \_\_marimo\_\_ files (session snapshots, thumbnails for OpenGraph previews)
• Includes selective .gitignore example for projects that need to version control session snapshots or assets

✅ Related Issue

Closes #7708

🙏 Thank You

Thanks to the marimo team for this amazing project! Happy to contribute to the documentation. Please let me know if any adjustments are needed.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	Mar 22, 2026 7:13pm

[github-actions]

Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.

---

I have read the CLA Document and I hereby sign the CLA

---

liwenjun-dev seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}

[Copilot]

Pull request overview

Adds a new “.gitignore best practices” section to the Marimo docs to clarify which __marimo__/ artifacts should typically be ignored vs. committed, addressing confusion raised in #7708.

Changes:

• Documents a recommended .gitignore pattern for ignoring __marimo__/ directories.
• Explains what __marimo__/cache/, __marimo__/session/, and __marimo__/assets/ are used for.
• Provides guidance and an example for selectively committing session snapshots and/or OpenGraph thumbnail assets.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The admonition has a blank line after !!! tip "When to commit ...". In MkDocs/Material admonitions, the content must follow immediately on the next indented line; the blank line can cause the tip body to render as a separate indented code block instead of tip content. Remove the blank line so the indented paragraph/list is part of the admonition.

Suggested change

[Copilot]

The “more selective .gitignore” example doesn’t match the explanation: !**/__marimo__/session/ and !**/__marimo__/assets/ are redundant here because those paths weren’t ignored by the preceding pattern (only cache/ is ignored). If the intent is “ignore all __marimo__ except session/assets”, note Git can’t re-include files inside an ignored directory unless the ignore rule ignores the directory contents (e.g., __marimo__/*) and then you unignore the desired subpaths. Please adjust the patterns and/or wording so the example actually enables committing session/assets while still ignoring the rest.

Suggested change

	For these cases, you can use a more selective `.gitignore`:
	```gitignore
	# Ignore cache only (recommended for most projects)
	**/__marimo__/cache/
	# Allow session snapshots and assets to be committed when needed
	!**/__marimo__/session/
	!**/__marimo__/assets/
	For these cases, you can use a more selective `.gitignore` that ignores
	everything in `__marimo__` except session snapshots and assets:
	```gitignore
	# Ignore all marimo-managed files by default
	**/__marimo__/*
	# Allow session snapshots and assets to be committed when needed
	!**/__marimo__/session/**
	!**/__marimo__/assets/**

[github-actions]

This pull request has been automatically marked as stale because it has not had activity in 30 days. It will be closed in 14 days if no further activity occurs. If this PR is still relevant, please leave a comment or push new changes to keep it open. Thank you for your contribution!