sync: add home branch mode

Author: nikivdev

docs/commands/jj.md

@@ -119,6 +119,9 @@ This keeps jj aligned with Git remotes while you work locally in jj.
 If you keep a long-lived personal branch on top of trunk, set `jj.home_branch` and treat it as
 your integration branch.
 
+When the current branch matches that home branch, plain `f sync` also switches into home-branch
+mode and syncs `origin/<default-branch>` into it instead of using the normal tracking pull.
+
 Then use short-lived `review/*` or `codex/*` branches on top of that home branch for task-specific
 work. `f status` is optimized to make that shape visible.
 

docs/commands/sync.md

@@ -13,6 +13,7 @@ Use this block when passing `f sync` behavior to another agent:
 - Default behavior: pull/sync only; push is off unless `--push`.
 - Defaults: `--stash=true`, `--fix=true`.
 - Modes: uses jj flow in healthy colocated workspaces, falls back to plain git when needed.
+- Home-branch mode: when the current branch matches `jj.home_branch`, `f sync` skips the normal tracking pull and syncs `origin/<default-branch>` into that branch.
 - Push target: configured `[git].remote` first, then standard fallback behavior.
 - Clipboard output: synced commit list is copied only when remote commit ranges are detected (typically jj fetch path).
 - Conflict note: jj can finish with unresolved conflicts and prints `jj resolve` guidance.
@@ -73,6 +74,25 @@ If an `upstream` remote exists (fork workflow), fetches and merges upstream chan
 
 If no `upstream` remote but on a feature branch, syncs from `origin/<default-branch>` (e.g. `origin/main`) into the current branch.
 
+### Home-branch mode
+
+If the current branch matches the resolved `jj.home_branch`, Flow treats that branch as your
+long-lived integration branch.
+
+In that mode, `f sync`:
+
+- skips the normal tracking-branch pull
+- leaves branch tracking config untouched
+- syncs `origin/<default-branch>` into the home branch
+- keeps all non-home branches on the existing sync behavior
+
+Home-branch resolution order is:
+
+1. `<repo>/flow.toml` `jj.home_branch`
+2. `~/.config/flow/flow.toml` `jj.home_branch`
+3. basename of `$HOME`
+4. `USER` or `USERNAME`
+
 ### Step 4: Push (optional)
 
 Only when `--push` is passed:
@@ -120,6 +140,9 @@ Set in `flow.toml` under `[git]`:
 ```toml
 [git]
 remote = "origin"  # default push remote
+
+[jj]
+home_branch = "alice" # optional long-lived personal integration branch
 ```
 
 ### Fork push

docs/flow-toml-spec.md

@@ -158,6 +158,7 @@ fr = "f run"
 - `[commit.skill_gate]`: optional required-skill policy for `f commit`; can enforce presence and minimum skill versions.
 - `[invariants]`: optional policy checks for forbidden patterns, dependency allowlists, terminology context, and file-size limits. `mode = "block"` makes invariant warnings fail `f invariants` and commit-time invariant gate checks.
 - `[git].remote`: preferred writable remote used by `f commit`/`f sync --push` (and jj remote defaults). Fallback order is `[git].remote`, then legacy `[jj].remote`, then `origin`.
+- `[jj].home_branch`: optional long-lived personal integration branch. When the current branch matches it, `f sync` switches into home-branch mode and syncs `origin/<default-branch>` into that branch. Resolution order is repo `flow.toml`, then `~/.config/flow/flow.toml`, then the basename of `$HOME`, then `USER` / `USERNAME`.
 
 ## Notes
 

docs/jj-home-branch-workflow.md

@@ -7,6 +7,7 @@ Flow supports that model directly through:
 
 - `f status` for a workflow-aware status view
 - `jj.home_branch` in `flow.toml`
+- `f sync` home-branch mode for pulling `origin/<default-branch>` into the home branch
 - `f jj workspace review <branch>` for isolated branch-specific working copies
 
 ## Mental model
@@ -28,6 +29,9 @@ default_branch = "main"
 home_branch = "alice"
 ```
 
+For `f sync`, if `jj.home_branch` is omitted, Flow falls back to the basename of `$HOME` and then
+`USER` / `USERNAME`.
+
 ## Status as the preflight
 
 Before switching branches, creating workspaces, committing, or publishing, run:

src/config.rs

@@ -505,6 +505,34 @@ pub struct JjConfig {
     pub review_prefix: Option<String>,
 }
 
+impl JjConfig {
+    pub(crate) fn merge(&mut self, other: JjConfig) {
+        if self.default_branch.is_none() {
+            self.default_branch = other.default_branch;
+        }
+        if self.remote.is_none() {
+            self.remote = other.remote;
+        }
+        if self.auto_track.is_none() {
+            self.auto_track = other.auto_track;
+        }
+        if self.home_branch.is_none() {
+            self.home_branch = other.home_branch;
+        }
+        if self.review_prefix.is_none() {
+            self.review_prefix = other.review_prefix;
+        }
+    }
+
+    fn is_empty(&self) -> bool {
+        self.default_branch.is_none()
+            && self.remote.is_none()
+            && self.auto_track.is_none()
+            && self.home_branch.is_none()
+            && self.review_prefix.is_none()
+    }
+}
+
 /// Git workflow config.
 #[derive(Debug, Clone, Deserialize, Serialize, Default)]
 pub struct GitConfig {
@@ -2489,6 +2517,8 @@ fn merge_config(base: &mut Config, other: Config) {
     }
     if base.jj.is_none() {
         base.jj = other.jj;
+    } else if let (Some(base_jj), Some(other_jj)) = (base.jj.as_mut(), other.jj) {
+        base_jj.merge(other_jj);
     }
     if base.everruns.is_none() {
         base.everruns = other.everruns;
@@ -2594,6 +2624,87 @@ fn preferred_git_remote_from_cfg(cfg: &Config) -> Option<String> {
         .and_then(|jj_cfg| first_non_empty_remote(jj_cfg.remote.as_deref()))
 }
 
+fn load_jj_config_from_path(path: &Path) -> Option<JjConfig> {
+    load(path).ok()?.jj
+}
+
+pub fn effective_jj_config_for_repo(repo_root: &Path) -> Option<JjConfig> {
+    let local_config = repo_root.join("flow.toml");
+    let local = if local_config.exists() {
+        load_jj_config_from_path(&local_config)
+    } else {
+        None
+    };
+
+    let global_config = default_config_path();
+    let global = if global_config.exists() {
+        load_jj_config_from_path(&global_config)
+    } else {
+        None
+    };
+
+    let merged = match (local, global) {
+        (Some(mut local), Some(global)) => {
+            local.merge(global);
+            Some(local)
+        }
+        (Some(local), None) => Some(local),
+        (None, Some(global)) => Some(global),
+        (None, None) => None,
+    }?;
+
+    (!merged.is_empty()).then_some(merged)
+}
+
+pub fn configured_home_branch_for_repo(repo_root: &Path) -> Option<String> {
+    effective_jj_config_for_repo(repo_root)
+        .and_then(|cfg| cfg.home_branch)
+        .and_then(|value| normalized_branch_name(&value))
+}
+
+fn normalized_branch_name(value: &str) -> Option<String> {
+    let trimmed = value.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+fn inferred_home_branch_from_sources(
+    home_dir: Option<&Path>,
+    user: Option<&str>,
+    username: Option<&str>,
+) -> Option<String> {
+    home_dir
+        .and_then(|path| path.file_name())
+        .and_then(|name| name.to_str())
+        .and_then(normalized_branch_name)
+        .or_else(|| user.and_then(normalized_branch_name))
+        .or_else(|| username.and_then(normalized_branch_name))
+}
+
+pub fn resolved_home_branch_for_repo(
+    repo_root: &Path,
+    default_branch: Option<&str>,
+) -> Option<String> {
+    if let Some(configured) = configured_home_branch_for_repo(repo_root) {
+        return Some(configured);
+    }
+
+    let home_dir = std::env::var_os("HOME").map(PathBuf::from);
+    let derived = inferred_home_branch_from_sources(
+        home_dir.as_deref(),
+        std::env::var("USER").ok().as_deref(),
+        std::env::var("USERNAME").ok().as_deref(),
+    )?;
+    let default_branch = default_branch.and_then(normalized_branch_name);
+    if default_branch.as_deref() == Some(derived.as_str()) {
+        return None;
+    }
+    Some(derived)
+}
+
 /// Resolve the preferred writable git remote for a repository.
 ///
 /// Precedence:
@@ -2643,7 +2754,7 @@ pub fn load_or_default<P: AsRef<Path>>(path: P) -> Config {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use std::path::PathBuf;
+    use std::path::{Path, PathBuf};
     use tempfile::tempdir;
 
     fn fixture_path(relative: &str) -> PathBuf {
@@ -3284,6 +3395,76 @@ remote = "myflow-i"
         );
     }
 
+    #[test]
+    fn jj_config_merge_fills_missing_fields_only() {
+        let mut local = JjConfig {
+            default_branch: Some("main".to_string()),
+            auto_track: Some(true),
+            ..Default::default()
+        };
+        let global = JjConfig {
+            default_branch: Some("trunk".to_string()),
+            remote: Some("origin".to_string()),
+            auto_track: Some(false),
+            home_branch: Some("nikiv".to_string()),
+            review_prefix: Some("review".to_string()),
+        };
+
+        local.merge(global);
+
+        assert_eq!(local.default_branch.as_deref(), Some("main"));
+        assert_eq!(local.remote.as_deref(), Some("origin"));
+        assert_eq!(local.auto_track, Some(true));
+        assert_eq!(local.home_branch.as_deref(), Some("nikiv"));
+        assert_eq!(local.review_prefix.as_deref(), Some("review"));
+    }
+
+    #[test]
+    fn inferred_home_branch_prefers_home_dir_basename() {
+        let home = Path::new("/Users/nikitavoloboev");
+
+        assert_eq!(
+            inferred_home_branch_from_sources(Some(home), Some("other-user"), Some("third-user")),
+            Some("nikitavoloboev".to_string())
+        );
+    }
+
+    #[test]
+    fn inferred_home_branch_falls_back_to_user_then_username() {
+        assert_eq!(
+            inferred_home_branch_from_sources(None, Some("nikiv"), Some("ignored")),
+            Some("nikiv".to_string())
+        );
+        assert_eq!(
+            inferred_home_branch_from_sources(None, None, Some("windows-user")),
+            Some("windows-user".to_string())
+        );
+    }
+
+    #[test]
+    fn inferred_home_branch_ignores_blank_values() {
+        assert_eq!(
+            inferred_home_branch_from_sources(None, Some("  "), Some("")),
+            None
+        );
+    }
+
+    #[test]
+    fn resolved_home_branch_for_repo_prefers_repo_config() {
+        let dir = tempdir().expect("tempdir");
+        let repo_root = dir.path();
+        fs::write(
+            repo_root.join("flow.toml"),
+            "[jj]\nhome_branch = \"nikiv\"\n",
+        )
+        .expect("write flow.toml");
+
+        assert_eq!(
+            resolved_home_branch_for_repo(repo_root, Some("main")),
+            Some("nikiv".to_string())
+        );
+    }
+
     #[test]
     fn analytics_config_parses() {
         let toml = r#"

src/jj.rs

@@ -1731,10 +1731,7 @@ fn current_workspace_name(workspace_root: &Path) -> Result<String> {
 }
 
 fn configured_home_branch(repo_root: &Path) -> Option<String> {
-    load_jj_config(repo_root)
-        .and_then(|cfg| cfg.home_branch)
-        .map(|value| value.trim().to_string())
-        .filter(|value| !value.is_empty())
+    config::configured_home_branch_for_repo(repo_root)
 }
 
 fn git_current_branch(repo_root: &Path) -> Option<String> {
@@ -2316,23 +2313,7 @@ fn auto_track_enabled(repo_root: &Path) -> bool {
 }
 
 fn load_jj_config(repo_root: &Path) -> Option<config::JjConfig> {
-    let local = repo_root.join("flow.toml");
-    if local.exists() {
-        if let Ok(cfg) = config::load(&local) {
-            if cfg.jj.is_some() {
-                return cfg.jj;
-            }
-        }
-    }
-    let global = config::default_config_path();
-    if global.exists() {
-        if let Ok(cfg) = config::load(&global) {
-            if cfg.jj.is_some() {
-                return cfg.jj;
-            }
-        }
-    }
-    None
+    config::effective_jj_config_for_repo(repo_root)
 }
 
 fn review_workspace_name(branch: &str) -> String {