feat: change RepositoryOpenFlags into options (#61)

* destruct repository opening options

* built

* update docs

* tests

Author: seokju-na

docs/README.md

@@ -11,7 +11,7 @@ Use following tags to create robust references using JSDoc.
 - `@throws` : Write documentation for errors that should be noted.
 - `@example` : Examples are not required, but are recommended as they make the behavior easier to understand.
 
-## Generate Reference
+## Generating Reference
 
 To automatically generate reference documentations after writing a JSDoc, please run the command below.
 

docs/ko/reference/Repository/openRepository.md

@@ -18,44 +18,42 @@ function openRepository(
   <li class="param-li param-li-root">
     <span class="param-name">path</span><span class="param-required">필수</span>&nbsp;·&nbsp;<span class="param-type">string</span>
     <br>
-    <p class="param-description">열려고 하는 기존 리포지토리의 디렉터리 경로예요.</p>
+    <p class="param-description">이미 존재하는 리포지토리가 위치한 디렉터리 경로예요.</p>
   </li>
   <li class="param-li param-li-root">
     <span class="param-name">options</span><span class="param-type">null | RepositoryOpenOptions</span>
     <br>
-    <p class="param-description">리포지토리 여는 방식을 설정하는 옵션이에요.</p>
+    <p class="param-description">리포지토리를 오픈할 때 적용할 옵션들을 설정할 수 있어요.</p>
     <ul class="param-ul">
+      <li class="param-li">
+        <span class="param-name">bare</span><span class="param-type">boolean</span>
+        <br>
+        <p class="param-description">이 옵션이 <code>true</code>로 설정되면, 리포지토리가 bare하지 않더라도 강제로 bare 형태로 열며, 워킹 디렉터리는 무시하고 리포지토리 구성을 성능 향상을 위해 지연해요.</p>
+      </li>
       <li class="param-li">
         <span class="param-name">ceilingDirs</span><span class="param-type">string[]</span>
         <br>
-        <p class="param-description">상위 디렉터리를 검색할 때, 이 목록에 포함된 디렉터리 이전에서 검색을 멈춰요.</p>
+        <p class="param-description">부모 디렉터리 탐색 중에, 진입하기 전에 멈출 경로들의 목록을 지정해요.</p>
+      </li>
+      <li class="param-li">
+        <span class="param-name">crossFs</span><span class="param-type">boolean</span>
+        <br>
+        <p class="param-description">이 옵션이 <code>true</code>로 설정되면, 상위 디렉터리 탐색 시 파일시스템 경계를 넘지 않도록 해요 (stat의 st_dev 값이 변경될 때 감지해요).</p>
+      </li>
+      <li class="param-li">
+        <span class="param-name">fromEnv</span><span class="param-type">boolean</span>
+        <br>
+        <p class="param-description">이 옵션이 <code>true</code>로 설정되면, <code>open</code>은 다른 옵션과 <code>ceilingDirs</code>를 무시하고 git이 사용하는 환경 변수를 따르게 돼요. 다만, <code>path</code>가 <code>$GIT_DIR</code>을 덮어써요.</p>
       </li>
       <li class="param-li">
-        <span class="param-name">flags</span><span class="param-required">필수</span>&nbsp;·&nbsp;<span class="param-type">number</span>
+        <span class="param-name">noDotgit</span><span class="param-type">boolean</span>
         <br>
-        <p class="param-description">
-<code>flags</code>에 따라 리포지토리를 여는 방식이 달라져요.
-<br>
-- <code>RepositoryOpenFlags.NoSearch</code> : 
-  <code>path</code>가 반드시 리포지토리 경로여야 해요.  
-  (<code>open</code>이 상위 디렉터리를 검색하지 않음)  
-  설정하지 않으면 서브디렉터리에서 호출해도 상위 디렉터리를 검색해요.
-<br>
-- <code>RepositoryOpenFlags.CrossFS</code> :
-  상위 디렉터리를 검색할 때 파일 시스템 경계를 넘지 않도록 설정해요.  
-  (<code>stat</code>의 <code>st_dev</code> 필드가 변경되면 검색을 중단)
-<br>
-- <code>RepositoryOpenFlags.Bare</code> :
-  <code>bare</code> 리포지토리로 강제로 열어요.  
-  (워킹 디렉터리를 무시하고, 성능을 위해 리포지토리 설정을 지연 로드)
-<br>
-- <code>RepositoryOpenFlags.NoDotgit</code> :
-  <code>path</code>에 자동으로 <code>/.git</code>을 추가하는 동작을 방지해요.
-<br>
-- <code>RepositoryOpenFlags.FromEnv</code> :
-  환경 변수를 기반으로 리포지토리를 열어요.  
-  (다른 플래그 및 <code>ceilingDirs</code> 설정을 무시하고 Git의 환경 변수 사용)  
-  단, <code>path</code> 값이 <code>$GIT_DIR</code>보다 우선돼요.</p>
+        <p class="param-description">이 옵션이 <code>true</code>로 설정되면, <code>path</code>에 <code>/.git</code>을 덧붙이지 않아요.</p>
+      </li>
+      <li class="param-li">
+        <span class="param-name">noSearch</span><span class="param-type">boolean</span>
+        <br>
+        <p class="param-description">이 옵션이 <code>true</code>로 설정되면, 경로가 리포지토리를 직접 가리켜야 해요. 그렇지 않으면 <code>open</code>이 상위 디렉터리로 탐색해요.</p>
       </li>
     </ul>
   </li>
@@ -86,22 +84,12 @@ import { openRepository } from 'es-git';
 const repo = await openRepository('/path/to/repo');
 ```
 
-bare 리포지토리를 열어요.
+`bare` 리포지토리를 열어요.
 
 ```ts
 import { openRepository } from 'es-git';
 
 const repo = await openRepository('/path/to/repo.git', {
   bare: true,
 });
-```
-
-하위 경로에서 리포지토리를 열어요.
-
-```ts
-import { openRepository, RepositoryOpenFlags } from 'es-git';
-
-const repo = await openRepository('/path/to/repo/sub/dir', {
-  flags: RepositoryOpenFlags.CrossFS,
-});
 ```

docs/reference/Repository/openRepository.md

@@ -25,15 +25,35 @@ function openRepository(
     <br>
     <p class="param-description">Options which can be used to configure how a repository is initialized.</p>
     <ul class="param-ul">
+      <li class="param-li">
+        <span class="param-name">bare</span><span class="param-type">boolean</span>
+        <br>
+        <p class="param-description">If this option is <code>true</code>, force opening the repository as bare event if it isn&#39;t, ignoring any working directory, and defer loading the repository configuration for performance.</p>
+      </li>
       <li class="param-li">
         <span class="param-name">ceilingDirs</span><span class="param-type">string[]</span>
         <br>
         <p class="param-description">ceiling_dirs specifies a list of paths that the search through parent directories will stop before entering.</p>
       </li>
       <li class="param-li">
-        <span class="param-name">flags</span><span class="param-required">required</span>&nbsp;·&nbsp;<span class="param-type">number</span>
+        <span class="param-name">crossFs</span><span class="param-type">boolean</span>
+        <br>
+        <p class="param-description">If this option is <code>true</code>, the search through parent directories will not cross a filesystem boundary (detected when the stat st_dev field changes).</p>
+      </li>
+      <li class="param-li">
+        <span class="param-name">fromEnv</span><span class="param-type">boolean</span>
+        <br>
+        <p class="param-description">If this option is <code>true</code>, <code>open</code> will ignore other options and <code>ceilingDirs</code>, and respect the same environment variables git does. Note, however, that <code>path</code> overrides <code>$GIT_DIR</code>.</p>
+      </li>
+      <li class="param-li">
+        <span class="param-name">noDotgit</span><span class="param-type">boolean</span>
         <br>
-        <p class="param-description">If flags contains <code>RepositoryOpenFlags.NoSearch</code>, the path must point directly to a repository; otherwise, this may point to a subdirectory of a repository, and <code>open</code> will search up through parent directories.  If flags contains <code>RepositoryOpenFlags.CrossFS</code>, the search through parent directories will not cross a filesystem boundary (detected when the stat st_dev field changes).  If flags contains <code>RepositoryOpenFlags.Bare</code>, force opening the repository as bare even if it isn&#39;t, ignoring any working directory, and defer loading the repository configuration for performance.  If flags contains <code>RepositoryOpenFlags.NoDotgit</code>, don&#39;t try appending <code>/.git</code> to <code>path</code>.  If flags contains <code>RepositoryOpenFlags.FromEnv</code>, <code>open</code> will ignore other flags and <code>ceilingDirs</code>, and respect the same environment variables git does. Note, however, that <code>path</code> overrides <code>$GIT_DIR</code>.</p>
+        <p class="param-description">If this options is <code>true</code>, don&#39;t try appending <code>/.git</code> to <code>path</code>.</p>
+      </li>
+      <li class="param-li">
+        <span class="param-name">noSearch</span><span class="param-type">boolean</span>
+        <br>
+        <p class="param-description">If this option is <code>true</code>, the path must point directly to a repository; otherwise, this may point to a subdirectory of a repository, and <code>open</code> will search up through parent directories.</p>
       </li>
     </ul>
   </li>
@@ -72,14 +92,4 @@ import { openRepository } from 'es-git';
 const repo = await openRepository('/path/to/repo.git', {
   bare: true,
 });
-```
-
-Open in a subdirectory of the repository
-
-```ts
-import { openRepository, RepositoryOpenFlags } from 'es-git';
-
-const repo = await openRepository('/path/to/repo/sub/dir', {
-  flags: RepositoryOpenFlags.CrossFS,
-});
 ```

index.d.ts

@@ -781,46 +781,35 @@ export interface RepositoryInitOptions {
 }
 export interface RepositoryOpenOptions {
   /**
-   * If flags contains `RepositoryOpenFlags.NoSearch`, the path must point
-   * directly to a repository; otherwise, this may point to a subdirectory
-   * of a repository, and `open` will search up through parent
+   * If this option is `true`, the path must point directly to a repository; otherwise,
+   * this may point to a subdirectory of a repository, and `open` will search up through parent
    * directories.
-   *
-   * If flags contains `RepositoryOpenFlags.CrossFS`, the search through parent
-   * directories will not cross a filesystem boundary (detected when the
-   * stat st_dev field changes).
-   *
-   * If flags contains `RepositoryOpenFlags.Bare`, force opening the repository as
-   * bare even if it isn't, ignoring any working directory, and defer
-   * loading the repository configuration for performance.
-   *
-   * If flags contains `RepositoryOpenFlags.NoDotgit`, don't try appending
-   * `/.git` to `path`.
-   *
-   * If flags contains `RepositoryOpenFlags.FromEnv`, `open` will ignore
-   * other flags and `ceilingDirs`, and respect the same environment
-   * variables git does. Note, however, that `path` overrides `$GIT_DIR`.
    */
-  flags: number
+  noSearch?: boolean
+  /**
+   * If this option is `true`, the search through parent directories will not cross
+   * a filesystem boundary (detected when the stat st_dev field changes).
+   */
+  crossFs?: boolean
+  /**
+   * If this option is `true`, force opening the repository as bare event if it isn't, ignoring
+   * any working directory, and defer loading the repository configuration for performance.
+   */
+  bare?: boolean
+  /** If this options is `true`, don't try appending `/.git` to `path`. */
+  noDotgit?: boolean
+  /**
+   * If this option is `true`, `open` will ignore other options and `ceilingDirs`, and respect
+   * the same environment variables git does.
+   * Note, however, that `path` overrides `$GIT_DIR`.
+   */
+  fromEnv?: boolean
   /**
    * ceiling_dirs specifies a list of paths that the search through parent
    * directories will stop before entering.
    */
   ceilingDirs?: Array<string>
 }
-/** Flags for opening repository. */
-export enum RepositoryOpenFlags {
-  /** Only open the specified path; don't walk upward searching. */
-  NoSearch = 1,
-  /** Search across filesystem boundaries. */
-  CrossFS = 2,
-  /** Force opening as a bare repository, and defer loading its config. */
-  Bare = 4,
-  /** Don't try appending `/.git` to the specified repository path. */
-  NoDotGit = 8,
-  /** Respect environment variables like `$GIT_DIR`. */
-  FromEnv = 16
-}
 export interface RepositoryCloneOptions {
   /**
    * Indicate whether the repository will be cloned as a bare repository or
@@ -923,16 +912,6 @@ export declare function initRepository(path: string, options?: RepositoryInitOpt
  *   bare: true,
  * });
  * ```
- *
- * Open in a subdirectory of the repository
- *
- * ```ts
- * import { openRepository, RepositoryOpenFlags } from 'es-git';
- *
- * const repo = await openRepository('/path/to/repo/sub/dir', {
- *   flags: RepositoryOpenFlags.CrossFS,
- * });
- * ```
  */
 export declare function openRepository(path: string, options?: RepositoryOpenOptions | undefined | null, signal?: AbortSignal | undefined | null): Promise<Repository>
 /**

index.js

@@ -162,46 +162,49 @@ impl From<&RepositoryInitOptions> for git2::RepositoryInitOptions {
 }
 
 #[napi(object)]
+#[derive(Clone, Default)]
 pub struct RepositoryOpenOptions {
-  /// If flags contains `RepositoryOpenFlags.NoSearch`, the path must point
-  /// directly to a repository; otherwise, this may point to a subdirectory
-  /// of a repository, and `open` will search up through parent
+  /// If this option is `true`, the path must point directly to a repository; otherwise,
+  /// this may point to a subdirectory of a repository, and `open` will search up through parent
   /// directories.
-  ///
-  /// If flags contains `RepositoryOpenFlags.CrossFS`, the search through parent
-  /// directories will not cross a filesystem boundary (detected when the
-  /// stat st_dev field changes).
-  ///
-  /// If flags contains `RepositoryOpenFlags.Bare`, force opening the repository as
-  /// bare even if it isn't, ignoring any working directory, and defer
-  /// loading the repository configuration for performance.
-  ///
-  /// If flags contains `RepositoryOpenFlags.NoDotgit`, don't try appending
-  /// `/.git` to `path`.
-  ///
-  /// If flags contains `RepositoryOpenFlags.FromEnv`, `open` will ignore
-  /// other flags and `ceilingDirs`, and respect the same environment
-  /// variables git does. Note, however, that `path` overrides `$GIT_DIR`.
-  pub flags: u32,
+  pub no_search: Option<bool>,
+  /// If this option is `true`, the search through parent directories will not cross
+  /// a filesystem boundary (detected when the stat st_dev field changes).
+  pub cross_fs: Option<bool>,
+  /// If this option is `true`, force opening the repository as bare event if it isn't, ignoring
+  /// any working directory, and defer loading the repository configuration for performance.
+  pub bare: Option<bool>,
+  /// If this options is `true`, don't try appending `/.git` to `path`.
+  pub no_dotgit: Option<bool>,
+  /// If this option is `true`, `open` will ignore other options and `ceilingDirs`, and respect
+  /// the same environment variables git does.
+  /// Note, however, that `path` overrides `$GIT_DIR`.
+  pub from_env: Option<bool>,
   /// ceiling_dirs specifies a list of paths that the search through parent
   /// directories will stop before entering.
   pub ceiling_dirs: Option<Vec<String>>,
 }
 
-#[napi]
-#[repr(u32)]
-/// Flags for opening repository.
-pub enum RepositoryOpenFlags {
-  /// Only open the specified path; don't walk upward searching.
-  NoSearch = 1,
-  /// Search across filesystem boundaries.
-  CrossFS = 2,
-  /// Force opening as a bare repository, and defer loading its config.
-  Bare = 4,
-  /// Don't try appending `/.git` to the specified repository path.
-  NoDotGit = 8,
-  /// Respect environment variables like `$GIT_DIR`.
-  FromEnv = 16,
+impl RepositoryOpenOptions {
+  pub fn flags(&self) -> git2::RepositoryOpenFlags {
+    let mut flags = git2::RepositoryOpenFlags::empty();
+    if let Some(true) = self.no_search {
+      flags.insert(git2::RepositoryOpenFlags::NO_SEARCH);
+    }
+    if let Some(true) = self.cross_fs {
+      flags.insert(git2::RepositoryOpenFlags::CROSS_FS);
+    }
+    if let Some(true) = self.bare {
+      flags.insert(git2::RepositoryOpenFlags::BARE);
+    }
+    if let Some(true) = self.no_dotgit {
+      flags.insert(git2::RepositoryOpenFlags::NO_DOTGIT);
+    }
+    if let Some(true) = self.from_env {
+      flags.insert(git2::RepositoryOpenFlags::FROM_ENV);
+    }
+    flags
+  }
 }
 
 #[napi(object)]
@@ -501,14 +504,10 @@ impl Task for OpenRepositoryTask {
   type JsValue = Repository;
 
   fn compute(&mut self) -> Result<Self::Output> {
-    let inner = if let Some(opts) = &self.options {
-      let flags = git2::RepositoryOpenFlags::from_bits_truncate(opts.flags);
-      let ceiling_dirs = opts.ceiling_dirs.to_owned().unwrap_or_default();
-      git2::Repository::open_ext(&self.path, flags, ceiling_dirs)
-    } else {
-      git2::Repository::open(&self.path)
-    }
-    .map_err(crate::Error::from)?;
+    let options = self.options.to_owned().unwrap_or_default();
+    let flags = options.flags();
+    let ceiling_dirs = options.ceiling_dirs.to_owned().unwrap_or_default();
+    let inner = git2::Repository::open_ext(&self.path, flags, ceiling_dirs).map_err(crate::Error::from)?;
     Ok(Repository { inner })
   }
 
@@ -556,16 +555,6 @@ impl Task for OpenRepositoryTask {
 ///   bare: true,
 /// });
 /// ```
-///
-/// Open in a subdirectory of the repository
-///
-/// ```ts
-/// import { openRepository, RepositoryOpenFlags } from 'es-git';
-///
-/// const repo = await openRepository('/path/to/repo/sub/dir', {
-///   flags: RepositoryOpenFlags.CrossFS,
-/// });
-/// ```
 pub fn open_repository(
   path: String,
   options: Option<RepositoryOpenOptions>,